A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Okta API is how an app or AI agent works with an Okta org: listing and creating users, adding people to groups, assigning applications, reading the system log, and deactivating an account when someone leaves. Access is granted through an API token or an OAuth access token carrying named scopes, each scope set to read or manage, and an agent is limited to the areas those scopes cover. Okta can also push events to an event hook when something happens, like a user being created or a session starting.
How an app or AI agent connects to Okta determines what it can reach. There are several routes, each governed by the token behind it and the scopes that token carries.
The Management API answers at the org base URL https://{yourOktaDomain} under /api/v1. It is resource-oriented JSON over HTTPS and is reached with either an OAuth 2.0 access token or an SSWS API token.
Okta's first-party MCP server connects an AI agent to an Okta org through the Model Context Protocol. It is self-hosted from the official okta-mcp-server project, authenticates with a service app using the Device Authorization Grant or Private Key JWT, and dynamically exposes only the tools its granted scopes allow. Destructive actions, like deletes and deactivations, prompt for confirmation.
Event hooks deliver chosen event types to a registered HTTPS URL with an outbound POST when each event fires. Okta confirms the endpoint once through a verification challenge that must be echoed back, then delivers events asynchronously with a three-second timeout and at most one retry.
A service app authenticates with Private Key JWT and receives an access token that carries only the scopes it was granted, in the form okta.
An API token is sent as 'Authorization: SSWS
The Okta Management API is split into areas an agent can act on, such as users, groups, applications, sessions, policies, and the system log. Each area has its own methods and its own scopes, and some grant access to far more than others.
List, read, create, update, replace, and delete users in the org.
Activate, deactivate, reactivate, suspend, unsuspend, and unlock a user account.
List, read, create, replace, and delete groups, list members, and add or remove a user.
List, read, create, replace, delete, activate, and deactivate the applications connected to the org.
List, assign, read, update, and unassign the users granted access to an application.
Read, refresh, and revoke a user's Okta session.
List, read, create, replace, delete, activate, and deactivate the policies that govern sign-in and security.
List, enroll, read, and unenroll the multi-factor authentication factors on a user.
Read the system log of events across the org for audit and monitoring.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
UsersList, read, create, update, replace, and delete users in the org.6 | ||||||
| GET | /api/v1/users | List users in the org, with optional search and filter. | read | okta.users.read | Current | |
An SSWS API token reaches this with the creating admin's permissions and ignores scopes. Acts onuser Permission (capability) okta.users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users | Create a user, optionally activating the account and setting credentials. | write | okta.users.manage | Current | |
There is no separate create scope; okta.users.manage covers create, update, and delete. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook event user.lifecycle.createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/users/{id} | Retrieve a single user by id, login, or login shortname. | read | okta.users.read | Current | |
Returns the user's profile, status, and credential metadata. Acts onuser Permission (capability) okta.users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/{id} | Update a user, applying a partial change to the profile or credentials. | write | okta.users.manage | Current | |
A POST applies a partial update; the PUT replace endpoint overwrites the whole profile. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook event user.account.update_profileRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/users/{id} | Replace a user, overwriting the full profile and credentials. | write | okta.users.manage | Current | |
Unset profile fields are cleared, unlike the partial POST update. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/users/{id} | Delete a user. The user must be deactivated first, so this is called twice or after a deactivate. | write | okta.users.manage | Current | |
Deletion is permanent and removes the account from the org. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
User lifecycleActivate, deactivate, reactivate, suspend, unsuspend, and unlock a user account.4 | ||||||
| POST | /api/v1/users/{id}/lifecycle/activate | Activate a staged or deactivated user so the account can sign in. | write | okta.users.manage | Current | |
Lifecycle transitions are their own endpoints, not a field on the user object. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/{id}/lifecycle/deactivate | Deactivate a user, which signs them out and blocks sign-in until reactivated. | write | okta.users.manage | Current | |
Deactivation is a prerequisite for deleting the user. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook event user.lifecycle.deactivateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/{id}/lifecycle/suspend | Suspend an active user, temporarily blocking sign-in while keeping the account. | write | okta.users.manage | Current | |
Suspend is reversible with unsuspend; the account and its data remain. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/{id}/lifecycle/unlock | Unlock a user who was locked out after too many failed sign-in attempts. | write | okta.users.manage | Current | |
Returns the user to active status without resetting their password. Acts onuser Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsList, read, create, replace, and delete groups, list members, and add or remove a user.6 | ||||||
| GET | /api/v1/groups | List groups in the org, with optional search and filter. | read | okta.groups.read | Current | |
Covers Okta groups, app groups, and rule-built groups. Acts ongroup Permission (capability) okta.groups.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/groups | Create an Okta group. | write | okta.groups.manage | Current | |
Creates a group of type OKTA_GROUP that members can be assigned to. Acts ongroup Permission (capability) okta.groups.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/groups/{groupId} | Retrieve a single group by id. | read | okta.groups.read | Current | |
Returns the group profile and type. Acts ongroup Permission (capability) okta.groups.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/groups/{groupId}/users | List the member users of a group. | read | okta.groups.read | Current | |
Returns the users currently in the group. Acts ongroup Permission (capability) okta.groups.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/groups/{groupId}/users/{userId} | Assign a user to a group. | write | okta.groups.manage | Current | |
Adds membership; the user gains anything that group grants, such as app access. Acts ongroup Permission (capability) okta.groups.manageVersionAvailable since the API’s base version Webhook event group.user_membership.addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/groups/{groupId}/users/{userId} | Remove a user from a group. | write | okta.groups.manage | Current | |
Removes membership and anything that group granted the user. Acts ongroup Permission (capability) okta.groups.manageVersionAvailable since the API’s base version Webhook event group.user_membership.removeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ApplicationsList, read, create, replace, delete, activate, and deactivate the applications connected to the org.3 | ||||||
| GET | /api/v1/apps | List the applications connected to the org. | read | okta.apps.read | Current | |
Returns each app's status, sign-on mode, and settings. Acts onapplication Permission (capability) okta.apps.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/apps | Create an application integration in the org. | write | okta.apps.manage | Current | |
Adds a new app that users and groups can then be assigned to. Acts onapplication Permission (capability) okta.apps.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/apps/{appId}/lifecycle/activate | Activate an application so it is available to assigned users. | write | okta.apps.manage | Current | |
Activation and deactivation are their own lifecycle endpoints. Acts onapplication Permission (capability) okta.apps.manageVersionAvailable since the API’s base version Webhook event application.lifecycle.activateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Application assignmentsList, assign, read, update, and unassign the users granted access to an application.3 | ||||||
| GET | /api/v1/apps/{appId}/users | List the users assigned to an application. | read | okta.apps.read | Current | |
Shows who can reach the app and their app-specific profile. Acts onapplication user Permission (capability) okta.apps.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/apps/{appId}/users | Assign a user to an application, granting them access to it. | write | okta.apps.manage | Current | |
Direct assignment; group assignment grants access through group membership instead. Acts onapplication user Permission (capability) okta.apps.manageVersionAvailable since the API’s base version Webhook event application.user_membership.addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/apps/{appId}/users/{userId} | Unassign a user from an application, removing their access. | write | okta.apps.manage | Current | |
Removes direct access; group-based access ends only when the group assignment is removed. Acts onapplication user Permission (capability) okta.apps.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SessionsRead, refresh, and revoke a user's Okta session.3 | ||||||
| GET | /api/v1/sessions/{sessionId} | Retrieve a user's Okta session by id. | read | okta.sessions.read | Current | |
Returns the session status, the user, and when it expires. Acts onsession Permission (capability) okta.sessions.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/sessions/{sessionId}/lifecycle/refresh | Refresh a session, extending its lifetime. | write | okta.sessions.manage | Current | |
Extends the session up to the policy maximum, it does not reset the absolute lifetime. Acts onsession Permission (capability) okta.sessions.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/sessions/{sessionId} | Revoke a session, signing the user out of Okta. | write | okta.sessions.manage | Current | |
Ends the session immediately; the user must sign in again. Acts onsession Permission (capability) okta.sessions.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PoliciesList, read, create, replace, delete, activate, and deactivate the policies that govern sign-in and security.4 | ||||||
| GET | /api/v1/policies | List policies of a given type, such as sign-on or password policies. | read | okta.policies.read | Current | |
A type query parameter selects the policy category to list. Acts onpolicy Permission (capability) okta.policies.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/policies | Create a policy that governs sign-in or security behavior. | write | okta.policies.manage | Current | |
Policies set org-wide rules, so this changes how everyone signs in. Acts onpolicy Permission (capability) okta.policies.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/policies/{policyId} | Retrieve a single policy by id. | read | okta.policies.read | Current | |
Returns the policy settings and its conditions. Acts onpolicy Permission (capability) okta.policies.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/policies/{policyId}/rules | List the rules within a policy. | read | okta.policies.read | Current | |
Rules decide which conditions trigger the policy and what action it takes. Acts onpolicy rule Permission (capability) okta.policies.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Factors (MFA)List, enroll, read, and unenroll the multi-factor authentication factors on a user.3 | ||||||
| GET | /api/v1/users/{userId}/factors | List the multi-factor authentication factors enrolled on a user. | read | okta.users.read | Current | |
Factors are governed by the user scopes, not a separate factor scope. Acts onfactor Permission (capability) okta.users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/{userId}/factors | Enroll a new authentication factor for a user. | write | okta.users.manage | Current | |
Some factor types need a follow-up activate call to finish enrollment. Acts onfactor Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/users/{userId}/factors/{factorId} | Unenroll a factor from a user. | write | okta.users.manage | Current | |
Removing the last factor can force re-enrollment at next sign-in, per policy. Acts onfactor Permission (capability) okta.users.manageVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
System logRead the system log of events across the org for audit and monitoring.1 | ||||||
| GET | /api/v1/logs | List system log events across the org, with filtering by time, actor, and event type. | read | okta.logs.read | Current | |
The log is read-only and is the source catalog for event hook event types. Acts onlog event Permission (capability) okta.logs.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Okta can notify an app or AI agent when something happens in an org, instead of the app repeatedly asking. Okta sends the event to an event hook URL that has been registered for the chosen event types, after a one-time verification handshake.
| Event | What it signals | Triggered by |
|---|---|---|
user.lifecycle.create | Fires when a new user is created in the org. | /api/v1/users |
user.lifecycle.deactivate | Fires when a user is deactivated. | /api/v1/users/{id}/lifecycle/deactivate |
user.account.update_profile | Fires when a user's profile is updated. | /api/v1/users/{id} |
group.user_membership.add | Fires when a user is added to a group. | /api/v1/groups/{groupId}/users/{userId} |
group.user_membership.remove | Fires when a user is removed from a group. | /api/v1/groups/{groupId}/users/{userId} |
application.lifecycle.activate | Fires when an application is activated. | /api/v1/apps/{appId}/lifecycle/activate |
application.user_membership.add | Fires when a user is assigned to an application. | /api/v1/apps/{appId}/users |
user.session.start | Fires when a user session starts, after a successful sign-in. | In-app only |
Okta limits how fast an app or AI agent can call, through per-org and per-endpoint request quotas plus a separate concurrent limit on how many requests can be in flight at once. The ceilings depend on the org plan and add-ons.
Okta meters requests with rate-limit buckets, where a bucket is a set of endpoints that share a quota over a time window. The most general bucket is the whole org, and finer buckets apply per endpoint and per client app, so heavy use of one endpoint does not drain the budget for others. A separate concurrent rate limit caps how many requests can be in flight at the same time, independent of the per-minute quota. The exact ceilings depend on the org plan, the HTTP method, the licenses bought, and add-ons such as DynamicScale, so they are not a single fixed number. Every response carries X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset so a client can see its remaining budget and when the window resets, and exceeding a limit returns HTTP 429 with errorCode E0000047.
List endpoints use cursor-based pagination through the limit query parameter and a Link response header. The header carries a rel="next" URL with the cursor for the following page, which should be followed rather than built by hand, and pagination ends when no rel="next" link is present. The limit parameter sets the page size, with a per-endpoint maximum, and the System Log uses the same Link-header model.
Requests and responses are JSON. Page sizes are capped per endpoint through the limit parameter, for example up to 200 users or 1000 System Log events per page, and some search and filter parameters have their own length limits. There is no single documented payload size limit across the whole API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | E0000001 | API validation failed. The request was reachable but a field is missing or invalid, with detail in the errorCauses array. | Read the errorCauses array, correct the named field, and resend. |
| 401 | E0000004 | Authentication failed. The credentials are missing, invalid, or expired. | Check the token and the Authorization header, then send valid credentials. |
| 401 | E0000011 | The API token provided is invalid. | Issue a fresh API token or access token and retry with it. |
| 403 | E0000006 | The caller does not have permission to perform the requested action, because the token lacks the required scope or the admin role lacks the right. | Grant the missing scope or role, then retry. |
| 404 | E0000007 | The requested resource was not found, or the token cannot see it. | Confirm the resource id and that the token has access to it. |
| 429 | E0000047 | The API call exceeded the rate limit for too many requests in the window. | Wait for the X-Rate-Limit-Reset time before retrying, and slow the request rate. |
Okta does not version the Management API by date. There is a single path version, v1, that is continuously updated, and dated changes ship through the API release notes rather than a new version string.
The Okta Management API uses a single path version, v1, that is continuously updated rather than versioned by date. New endpoints and fields are added over time, and notable changes ship through the monthly API release notes for the Identity Engine and Classic Engine. The entries below are recent dated highlights from those release notes.
Through 2025 the Identity Engine API gained new management capabilities, delivered as additive changes to v1 and announced in the API release notes rather than as a new version string.
An integration tracks changes through the release notes rather than pinning a version.
Okta API release notes ↗Bollard AI sits between a team's AI agents and Okta. Grant each agent exactly the access it needs, read or manage, area by area, and every call is checked and logged.