Okta API Dictionary

Complete API Reference · Visual HTTP Flows · Use Case Dictionary · AI / MCP / OpenClaw Integration Patterns

Okta Management API — Full Endpoint Dictionary

Every API domain with endpoints, methods, descriptions, and OAuth scopes

The Okta API is REST-based, versioned at /api/v1/, and supports both OAuth 2.0 access tokens (recommended) and SSWS API tokens for authentication. All calls require HTTPS. Rate limits vary by endpoint (typically 600/min for users, 500/min for groups, 100/min for apps). Pagination uses cursor-based after parameters. Requests support If-Match ETags for optimistic concurrency on user profiles.
U
Users API
CRUD + lifecycle + credentials + linked objects
600/min
▸
POST/api/v1/users?activate=trueCreate + activate userokta.users.manage
GET/api/v1/users?search=profile.email eq "{e}"Search users (SCIM filter)okta.users.read
GET/api/v1/users/{userId}Get user by IDokta.users.read
PUT/api/v1/users/{userId}Full profile replaceokta.users.manage
POST/api/v1/users/{userId}Partial profile update (with If-Match ETag)okta.users.manage
POST/api/v1/users/{userId}/lifecycle/activateActivate pending userokta.users.manage
POST/api/v1/users/{userId}/lifecycle/deactivateDeactivate userokta.users.manage
POST/api/v1/users/{userId}/lifecycle/suspendSuspend userokta.users.manage
POST/api/v1/users/{userId}/lifecycle/unsuspendUnsuspend userokta.users.manage
POST/api/v1/users/{userId}/lifecycle/reset_passwordTrigger password resetokta.users.manage
POST/api/v1/users/{userId}/lifecycle/unlockUnlock locked-out userokta.users.manage
DEL/api/v1/users/{userId}Delete (must be deactivated)okta.users.manage
GET/api/v1/users/{userId}/groupsList user's groupsokta.users.read
GET/api/v1/users/{userId}/appLinksList user's assigned appsokta.users.read
G
Groups API
CRUD + membership + rules
500/min
▸
POST/api/v1/groupsCreate groupokta.groups.manage
GET/api/v1/groups?q={name}Search groupsokta.groups.read
GET/api/v1/groups/{groupId}Get group by IDokta.groups.read
PUT/api/v1/groups/{groupId}Update group profileokta.groups.manage
DEL/api/v1/groups/{groupId}Delete groupokta.groups.manage
GET/api/v1/groups/{groupId}/usersList membersokta.groups.read
PUT/api/v1/groups/{gid}/users/{uid}Add user to groupokta.groups.manage
DEL/api/v1/groups/{gid}/users/{uid}Remove user from groupokta.groups.manage
GET/api/v1/groups/{groupId}/appsList apps assigned to groupokta.groups.read
GET/api/v1/groups/rulesList group rulesokta.groups.read
POST/api/v1/groups/rulesCreate group ruleokta.groups.manage
A
Applications API
CRUD + user/group assignment + credentials
100/min
▸
GET/api/v1/appsList all appsokta.apps.read
POST/api/v1/appsCreate app integrationokta.apps.manage
GET/api/v1/apps/{appId}Get app by IDokta.apps.read
PUT/api/v1/apps/{appId}Update appokta.apps.manage
DEL/api/v1/apps/{appId}Deactivate + delete appokta.apps.manage
PUT/api/v1/apps/{appId}/users/{uid}Assign user to appokta.apps.manage
DEL/api/v1/apps/{appId}/users/{uid}Unassign user from appokta.apps.manage
PUT/api/v1/apps/{appId}/groups/{gid}Assign group to appokta.apps.manage
GET/api/v1/apps/{appId}/usersList app usersokta.apps.read
GET/api/v1/apps/{appId}/groupsList app groupsokta.apps.read
F
Factors API
MFA enrollment + verification + lifecycle
100/min
▸
GET/api/v1/users/{userId}/factorsList enrolled factorsokta.users.read
GET/api/v1/users/{userId}/factors/catalogList available factorsokta.users.read
POST/api/v1/users/{userId}/factorsEnroll a factorokta.users.manage
POST/api/v1/users/{uid}/factors/{fid}/verifyVerify a factorokta.users.manage
DEL/api/v1/users/{uid}/factors/{fid}Unenroll a factorokta.users.manage
P
Policies API
Sign-on + password + MFA + authorization policies
100/min
▸
GET/api/v1/policies?type={type}List by type: OKTA_SIGN_ON, PASSWORD, MFA_ENROLLokta.policies.read
GET/api/v1/policies/{policyId}Get policyokta.policies.read
POST/api/v1/policiesCreate policyokta.policies.manage
PUT/api/v1/policies/{policyId}Update policyokta.policies.manage
GET/api/v1/policies/{policyId}/rulesList policy rulesokta.policies.read
POST/api/v1/policies/{policyId}/rulesCreate policy ruleokta.policies.manage
L
System Log API
Audit events + filtering + streaming
120/min
▸
GET/api/v1/logs?since={ts}&until={ts}&filter=eventType eq "user.session.start"Query system log with SCIM filter, time range, sortOrder, limitokta.logs.read
O
OAuth 2.0 / OIDC Endpoints
Authorization servers + token + authorize + userinfo + keys
Per server
▸
GET/oauth2/{authServerId}/v1/authorizeAuthorization endpoint (OIDC)Per auth server
POST/oauth2/{authServerId}/v1/tokenToken endpoint (exchange code/refresh)Per auth server
GET/oauth2/{authServerId}/v1/userinfoUserInfo endpoint (OIDC claims)openid
GET/oauth2/{authServerId}/v1/keysJWKS (public keys for token validation)Public
POST/oauth2/{authServerId}/v1/introspectToken introspectionPer auth server
POST/oauth2/{authServerId}/v1/revokeToken revocationPer auth server
GET/oauth2/{authServerId}/.well-known/openid-configurationDiscovery documentPublic
GET/api/v1/authorizationServersList custom auth serversokta.authorizationServers.read
POST/api/v1/authorizationServersCreate custom auth serverokta.authorizationServers.manage
S
Sessions / Authentication / Devices
Primary authn + session mgmt + device lifecycle
Various
▸
POST/api/v1/authnPrimary authentication (username + password)Public
POST/api/v1/sessionsCreate session with session tokenokta.sessions.manage
GET/api/v1/sessions/{sessionId}Get sessionokta.sessions.read
DEL/api/v1/sessions/{sessionId}Revoke sessionokta.sessions.manage
GET/api/v1/devicesList devicesokta.devices.read
DEL/api/v1/devices/{deviceId}Delete deviceokta.devices.manage

Visual HTTP Data Flows

Step-by-step HTTP request/response flows for common Okta operations

Create user + assign to group + provision app
Client
STEP 1
Create user
POST /api/v1/users?activate=true
Body: {"profile":{"firstName":"John","lastName":"Doe","email":"mailto:jdoe@corp.com","login":"mailto:jdoe@corp.com"}}
Response: 201 Created → userId: 00u1abc...
Okta
▼
Client
STEP 2
Resolve group ID
GET /api/v1/groups?q=Engineering
Response: 200 OK → groupId: 00g5xyz...
Okta
▼
Client
STEP 3
Add user to group
PUT /api/v1/groups/00g5xyz/users/00u1abc
Response: 204 No Content — user is now a member of Engineering
Okta
▼
Client
STEP 4
Assign user to Jira app
PUT /api/v1/apps/0oa9jira/users/00u1abc
Body: {"id":"00u1abc","scope":"USER","profile":{"jiraUsername":"jdoe"}}
Response: 200 OK — app user created with profile mapping
Okta
▼
Client
STEP 5
Verify — read back user state
GET /api/v1/users/00u1abc → status: ACTIVE
GET /api/v1/users/00u1abc/groups → includes Engineering
GET /api/v1/users/00u1abc/appLinks → includes Jira
Okta
OAuth 2.0 Authorization Code + PKCE flow
App
STEP 1
Generate PKCE pair + redirect to authorize
code_verifier = random(43-128 chars)
code_challenge = BASE64URL(SHA256(code_verifier))
GET /oauth2/default/v1/authorize?response_type=code&client_id=X&redirect_uri=Y&scope=openid profile&code_challenge=Z&code_challenge_method=S256&state=abc
Okta
▼
Okta
STEP 2
User authenticates + MFA
Okta Sign-In Widget renders. User enters credentials. Sign-on policy evaluated. MFA challenged if required. On success → redirect to callback with auth code.
User
▼
Okta
STEP 3
Redirect with authorization code
302 → https://app.com/callback?code=AUTH_CODE&state=abc
App
▼
App
STEP 4
Exchange code for tokens
POST /oauth2/default/v1/token
Body: grant_type=authorization_code&code=AUTH_CODE&redirect_uri=Y&code_verifier=ORIGINAL_VERIFIER
Okta computes SHA256(code_verifier) and compares to stored challenge.
Response: 200 OK → {"access_token":"eyJ...","id_token":"eyJ...","refresh_token":"..."}
Okta
Employee offboarding — full deprovisioning chain
HR System
STEP 1
HR triggers termination event
Workday sends SCIM deprovision event or webhook to Okta Workflows. Alternatively, API call: POST /api/v1/users/{userId}/lifecycle/deactivate
Okta
▼
Okta
STEP 2
Cascade deprovision to all apps
Lifecycle management automatically removes user from all SCIM-provisioned apps. For each app: DELETE /api/v1/apps/{appId}/users/{userId}. For non-SCIM apps: SSO session invalidated.
Downstream Apps
▼
Okta
STEP 3
Revoke all sessions + factors
DELETE /api/v1/users/{userId}/sessions — all active sessions terminated.
All enrolled MFA factors automatically removed. User status transitions to DEPROVISIONED.
Terminated
▼
ISPM
STEP 4
Verify no residual access
ISPM confirms user has zero active app assignments, group memberships, or sessions. Generates compliance evidence for offboarding audit. System log event: user.lifecycle.deactivate
Audit

Use Case Dictionary — API-Enabled Scenarios

Real-world identity use cases with the exact API calls required to implement each one

User Lifecycle
Automated employee onboarding
HR creates record → Okta provisions user + assigns groups by department + provisions apps via SCIM + enrolls MFA + sends activation email.
POST /users?activate=true
GET /groups?q={dept}
PUT /groups/{gid}/users/{uid}
PUT /apps/{appId}/users/{uid}
POST /users/{uid}/factors (auto-enroll)
User Lifecycle
Bulk user import + migration
Migrate 10,000 users from legacy IdP to Okta with password import inline hooks, preserving existing credentials without forcing resets.
POST /users?activate=false (staged)
Body includes credentials.password.hook
POST /users/{uid}/lifecycle/activate (batch)
Group & Entitlements
Dynamic group rules for role-based access
Auto-assign users to groups based on department, title, or custom attributes. When a user's profile changes, group membership updates automatically.
POST /groups/rules
Body: {"type":"group_rule","conditions":{"expression":{"value":"user.department=='Engineering'"}},"actions":{"assignUserToGroups":{"groupIds":["{gid}"]}}}
App Management
Provision SAML/OIDC app + assign group
Create a SAML 2.0 app integration, configure SSO settings, then assign an entire group to the app for automatic access.
POST /apps (signOnMode: SAML_2_0)
PUT /apps/{appId}/groups/{gid}
GET /apps/{appId}/users (verify)
Authentication
Custom OAuth 2.0 auth server for API protection
Create a custom authorization server with scopes and claims for securing your REST APIs. Configure access policies per client.
POST /authorizationServers
POST /authorizationServers/{id}/scopes
POST /authorizationServers/{id}/claims
POST /authorizationServers/{id}/policies
GET /oauth2/{id}/v1/keys (JWKS)
Authentication
Enforce MFA on high-risk sign-on
Create sign-on policy requiring FIDO2 factor when risk score is HIGH or device is unmanaged. Apply to sensitive apps only.
POST /policies (type: OKTA_SIGN_ON)
POST /policies/{pid}/rules
Conditions: risk.level == "HIGH" || device.managed == false
Actions: requireFactor: {type: "webauthn"}
Governance
Security audit — failed logins last 30 days
Query system log for all failed authentication events. Filter by actor, time range, and event type. Export to SIEM for SOC investigation.
GET /logs?since=2025-01-01&filter=eventType eq "user.session.start" AND outcome.result eq "FAILURE"&limit=1000&sortOrder=DESCENDING
Non-Human Identity
Service account management + rotation
Create service account for CI/CD pipeline. Set credential rotation policy. Monitor usage via system log. Decommission when pipeline is retired.
POST /users (service account type)
POST /users/{uid}/credentials/change_password
GET /logs?filter=http://actor.id eq "{svcAcctId}"
POST /users/{uid}/lifecycle/deactivate
AI / MCP
Natural language identity management via MCP
"Create jdoe and add to Engineering" → MCP server translates to structured API calls → Okta executes → returns natural language confirmation.
MCP Client → Okta MCP Server
Tools: create_user, add_user_to_group,
assign_app_to_user, list_users,
get_system_logs
Auth: OAuth 2.0 (Device Grant or PKI JWT)
AI / MCP
AI-generated security audit report
"Generate a security audit for the last 30 days highlighting all group membership changes" → MCP queries logs → LLM formats into structured report.
MCP Client → Okta MCP Server
Tool: get_system_logs
Filter: eventType sw "group.user_membership"
LLM: formats + summarizes + highlights anomalies
AI / OpenClaw
OpenClaw agent orchestrates JML workflow
OpenClaw AI agent receives HR webhook → decomposes into identity operations → calls Okta via MCP → verifies completion → updates ITSM ticket.
OpenClaw Agent → Okta MCP Server
+ ServiceNow MCP Server
Chain: create_user → add_to_group →
assign_apps → verify → update_ticket

Okta MCP Server — AI Agent Integration

Model Context Protocol server for natural language identity management

The Okta MCP Server is a secure protocol abstraction layer that enables AI agents and LLMs to interact with the Okta org using natural language. It translates NL instructions into structured API calls, enforces scoped OAuth 2.0 permissions, creates full audit trails, and now integrates the MCP Elicitation API for human oversight on destructive actions (deleting apps, deactivating users require explicit confirmation). The server is open-source on GitHub, supports Docker deployment, and works with Claude Desktop, VS Code, Cursor, and agent frameworks like LangGraph.
MCP Server — end-to-end request flow
User / Agent
STEP 1
Natural language command
"Show me all failed login attempts from the last 24 hours" via Claude Desktop, VS Code, or Cursor.
MCP Client
▼
MCP Client
STEP 2
Route to Okta MCP server
MCP client securely routes command to the Okta MCP server instance. Transport: STDIO (local) or HTTP/SSE (remote).
MCP Server
▼
MCP Server
STEP 3
Authenticate + scope validation
Server authenticates with Okta org via Device Authorization Grant (interactive) or Private Key JWT (headless). Validates that granted scopes cover required actions: okta.logs.read.
Okta APIs
▼
MCP Server
STEP 4
Translate to API call + execute
Tool selected: get_system_logs
API call: GET /api/v1/logs?since=24h_ago&filter=outcome.result eq "FAILURE"
Okta returns structured JSON log events.
Okta APIs
▼
MCP Server
STEP 5
Return structured data to LLM
Server passes raw API response to LLM. LLM formats into natural language: "There were 47 failed login attempts in the last 24 hours. 23 from IP 192.168.1.x (possible credential stuffing)..."
LLM → User
Available MCP tools (from the okta-mcp-server repo): create_user, get_user, list_users, update_user, deactivate_user, delete_user, create_group, list_groups, add_user_to_group, remove_user_from_group, list_applications, assign_user_to_app, get_system_logs, list_policies, and more. Destructive operations (delete, deactivate) now trigger the MCP Elicitation API requiring explicit human confirmation before execution.
Authentication modes:
1. Device Authorization Grant (interactive) — browser-based login. Best for local dev with Claude Desktop or Cursor. Server triggers browser login, exchanges for scoped access token.
2. Private Key JWT (headless) — cryptographic key pair. Best for CI/CD, backend services, OpenClaw agents. Register public key in Okta, server signs requests with private key. No browser needed.
Destructive action with Elicitation API (human-in-the-loop)
Agent
STEP 1
"Delete user mailto:jdoe@corp.com"
Agent sends delete request to MCP server. Server detects this is a destructive operation.
MCP Server
▼
MCP Server
STEP 2
Elicitation: request human confirmation
MCP Elicitation API triggers a UI dialog: "Are you sure you want to delete user mailto:jdoe@corp.com? This action is irreversible." User must explicitly accept or decline.
Human
▼
Human
STEP 3
Confirmed → execute
Only on explicit "Accept": POST /api/v1/users/{uid}/lifecycle/deactivate then DELETE /api/v1/users/{uid}. Full audit trail logged. On "Decline": operation cancelled, agent notified.
Okta APIs

OpenClaw / AI Agent Integration Patterns

How AI orchestration platforms connect to Okta for identity automation

OpenClaw (and similar platforms like LangGraph, AutoGen, CrewAI) can leverage the Okta MCP server as a tool provider to orchestrate complex identity workflows. The key architectural pattern is: the AI orchestrator decomposes a high-level goal into sub-tasks, each sub-task maps to an MCP tool call against Okta, and the orchestrator chains these calls with dependency management, error handling, and rollback logic. This integrates with Cross App Access (XAA) for scoped, time-bound authorization and ISPM for continuous posture monitoring of the agent itself.
Conceptual architecture: OpenClaw → MCP → Okta
OpenClaw Agent
LLM orchestrator
Task decomposition
Dependency DAG
Rollback logic
→MCP Protocol
STDIO / HTTP
Okta MCP Server
Tool registry
Scope validation
Elicitation (HITL)
Audit logging
→OAuth 2.0
Scoped tokens
Okta Platform
Users, groups, apps
Policies, factors
System log
OIG, OPA, ISPM
Multi-MCP server chaining: OpenClaw can connect to multiple MCP servers simultaneously. Example: Okta MCP server for identity operations + Google Drive MCP server for reporting + ServiceNow MCP server for ticketing. The agent chains: "Find all locked users → create a spreadsheet → open an IT ticket for each" — one natural language instruction triggers a multi-system workflow.
OpenClaw: automated new hire onboarding (multi-MCP)
HR Webhook
TRIGGER
New hire event from Workday
Webhook payload: {"employee":"Jane Smith","dept":"Marketing","startDate":"2026-04-01","manager":"Bob Lee"}
OpenClaw
▼
OpenClaw
STEP 1
Decompose into identity tasks
LLM plans DAG: (1) Create Okta user → (2) Add to Marketing group → (3) Assign Slack, HubSpot, Canva apps → (4) Send welcome email via Gmail MCP → (5) Create IT ticket via ServiceNow MCP
Planner
▼
OpenClaw
STEP 2
Execute via Okta MCP server
create_user → add_user_to_group → assign_user_to_app × 3
All calls scoped to okta.users.manage okta.groups.manage okta.apps.manage
Okta MCP
▼
OpenClaw
STEP 3
Cross-MCP: email + ticket
Gmail MCP: send welcome email with login instructions + TAP code
ServiceNow MCP: create RITM ticket for laptop provisioning with new hire details
Gmail + SNOW
▼
OpenClaw
STEP 4
Verify + report
Read back from Okta: user ACTIVE ✓, groups confirmed ✓, apps assigned ✓
Agent reports: "Jane Smith onboarded successfully. Okta account active, 3 apps provisioned, welcome email sent, laptop ticket #INC0012345 created."
Complete
Security considerations for AI agent integration:
• Least privilege: Grant only the OAuth scopes the agent needs. Don't use super-admin tokens. The MCP server blocks calls that exceed granted scopes.
• Elicitation for destructive ops: Delete/deactivate operations require human confirmation via the MCP Elicitation API. This is non-bypassable.
• Audit trail: Every MCP tool call is logged in Okta system log + the MCP server's own audit stream. Correlate with SIEM for full visibility.
• ISPM monitoring: Register the AI agent as a managed identity in Universal Directory. ISPM tracks its OAuth grants, permission scope, and usage patterns. Detect if the agent's permissions drift or if unauthorized agents appear.
• XAA for cross-app: When the agent needs to access a downstream app (not just Okta admin), use Cross App Access (XAA) for scoped, time-bound delegated tokens instead of storing static credentials.