Okta Management API — user lifecycle and group membership

This reference is readable without JavaScript. Download the OpenAPI document.

Runtime

/api/purple-suite/{instanceId}/contracts/identity/okta
[
  {
    "method": "get",
    "path": "/api/v1/users/:id",
    "operationId": "getUser"
  },
  {
    "method": "post",
    "path": "/api/v1/users/:id/lifecycle/unlock",
    "operationId": "unlockUser"
  },
  {
    "method": "post",
    "path": "/api/v1/users/:id/lifecycle/forgot_password",
    "operationId": "forgotPasswordLifecycle"
  },
  {
    "method": "post",
    "path": "/api/v1/users/:id/lifecycle/expire_password",
    "operationId": "expirePassword"
  },
  {
    "method": "post",
    "path": "/api/v1/users/:userId/credentials/forgot_password",
    "operationId": "forgotPassword"
  },
  {
    "method": "get",
    "path": "/api/v1/users/:id/groups",
    "operationId": "listUserGroups"
  },
  {
    "method": "put",
    "path": "/api/v1/groups/:groupId/users/:userId",
    "operationId": "assignUserToGroup"
  },
  {
    "method": "get",
    "path": "/api/v1/groups/:groupId/users",
    "operationId": "listGroupUsers"
  }
]

Credentials

Coverage and limitations

{
  "documentScope": "bounded",
  "runtimeFidelity": "modeled",
  "counts": {
    "operations": 8
  },
  "notes": [
    "7 of the 726 pinned operations are served, plus one disclosed addition. They are exactly the calls the Moveworks account natives make (status, unlock, reset password, change password) and the Okta-group natives make (add to group, a user's groups, a group's members). The rest stay in the pin and are counted by tag in coverage.md.",
    "POST /api/v1/users/{id}/lifecycle/forgot_password is a disclosed addition: the reset-password native calls it, Okta's Terraform provider lists it as a live route, and no published Okta OpenAPI declares it. It shares one handler with the pinned POST /api/v1/users/{userId}/credentials/forgot_password.",
    "getUser is narrowed: the Content-Type okta-response header and the expand query parameter are removed from the served document because the adapter does not honour them.",
    "Ids are strict. The contract knows the users and groups the roster seeds and the rows an eval imports; imported rows win over roster rows in either order, and a lookup never creates a user or group.",
    "Everyone is a BUILT_IN group with implicit membership for every user; no membership row is stored for it.",
    "assignUserToGroup stores a membership only for an OKTA_GROUP group, as the pin says; on BUILT_IN Everyone or an imported APP_GROUP it answers 501 E0000060 ('Unsupported operation.'), the refusal Okta's support article shows for adding a user to a built-in or non-Okta group. The pin declares no 501 for the operation.",
    "Unlock on a user whose status is not LOCKED_OUT answers 403 E0000032, ACTIVE included, and still appends a refused lifecycle row. The pin's unlockUser also unlocks an ACTIVE user blocked from unknown devices; the mock has no device block, and the pin does not say what an unblocked ACTIVE user gets. The refusal is inferred from Okta's error-code reference (E0000032, 403, 'Unlock is not allowed for this user.') and from the Moveworks unlock native, which maps a 403 on a user it read as not LOCKED_OUT to NOOP.",
    "expire_password on a STAGED, PROVISIONED, SUSPENDED or DEPROVISIONED user answers 403 E0000038.",
    "forgot_password runs on ACTIVE and PASSWORD_EXPIRED users and answers 403 E0000034 on any other status, with a refused lifecycle row. The pin allows only ACTIVE in its text, and its PASSWORD_EXPIRED example still links forgotPassword; E0000034 is Okta's error-code reference entry ('Forgot password not allowed on specified user.').",
    "resetPasswordUrl points at the path-addressed base and is not itself a served route; it only proves a reset was issued. Each lifecycle call appends an okta_user_lifecycle row.",
    "_links and _embedded are not emitted: they would carry absolute vendor URLs.",
    "Auth refusals: an unknown instance is 404 E0000007, a wrong key on a locked-out instance is 429 E0000047, a registry failure is 500 E0000009, and a missing or wrong key is 401 E0000011. 429 is otherwise never emitted.",
    "listGroupUsers limit defaults to and is capped at 1000; members are ordered by Okta user id, and Link carries after first, as the Moveworks Okta client's cursor regex requires.",
    "People come from the shared PurpleSuite identity roster, so an Okta user here is the same human the instance's other apps know, joined on email."
  ]
}

Allows customers to easily access the Okta Management APIs

Servers

[
  {
    "url": "/api/purple-suite/{instanceId}/contracts/identity/okta"
  }
]

Authentication schemes

{
  "apiToken": {
    "description": "Pass the API token as the Authorization header value prefixed with SSWS: `Authorization: SSWS {API Token}`",
    "name": "Authorization",
    "type": "apiKey",
    "in": "header"
  },
  "oauth2": {
    "type": "oauth2",
    "description": "Pass the access_token as the value of the Authorization header: `Authorization: Bearer {access_token}`",
    "flows": {
      "authorizationCode": {
        "authorizationUrl": "/oauth2/v1/authorize",
        "tokenUrl": "/oauth2/v1/token",
        "scopes": {
          "okta.agentPools.manage": "Allows the app to create and manage agent pools in your Okta organization",
          "okta.agentPools.read": "Allows the app to read agent pools in your Okta organization",
          "okta.apiTokens.manage": "Allows the app to manage API Tokens in your Okta organization",
          "okta.apiTokens.read": "Allows the app to read API Tokens in your Okta organization",
          "okta.appGrants.manage": "Allows the app to create and manage grants in your Okta organization",
          "okta.appGrants.read": "Allows the app to read grants in your Okta organization",
          "okta.apps.interclientTrust.manage": "Allows the app to manage trusted relationship for native to web SSO",
          "okta.apps.interclientTrust.read": "Allows the app to read configured trusted relationship for native to web SSO",
          "okta.apps.manage": "Allows the app to create and manage Apps in your Okta organization",
          "okta.apps.read": "Allows the app to read information about Apps in your Okta organization",
          "okta.authenticators.manage": "Allows the app to manage all authenticators. For example, enrollments or resets.",
          "okta.authenticators.read": "Allows the app to read org authenticators information",
          "okta.authorizationServers.manage": "Allows the app to create and manage Authorization Servers in your Okta organization",
          "okta.authorizationServers.read": "Allows the app to read information about Authorization Servers in your Okta organization",
          "okta.behaviors.manage": "Allows the app to create and manage behavior detection rules in your Okta organization",
          "okta.behaviors.read": "Allows the app to read behavior detection rules in your Okta org",
          "okta.botProtection.manage": "Allows the app to manage bot protection configuration in your Okta org",
          "okta.botProtection.read": "Allows the app to read bot protection configuration in your Okta org",
          "okta.brands.manage": "Allows the app to create and manage Brands and Themes in your Okta organization",
          "okta.brands.read": "Allows the app to read information about Brands and Themes in your Okta organization",
          "okta.captchas.manage": "Allows the app to create and manage CAPTCHAs in your Okta organization",
          "okta.captchas.read": "Allows the app to read information about CAPTCHAs in your Okta organization",
          "okta.customTelephonyProvider.manage": "Allows the app to create and manage custom telephony provider credentials",
          "okta.customTelephonyProvider.read": "Allows the app to read custom telephony provider credentials",
          "okta.deviceAssurance.manage": "Allows the app to manage device assurances",
          "okta.deviceAssurance.read": "Allows the app to read device assurances",
          "okta.deviceIntegrations.manage": "Allows the app to manage device integrations",
          "okta.deviceIntegrations.read": "Allows the app to read device integrations",
          "okta.devicePostureChecks.manage": "Allows the app to manage device posture checks",
          "okta.devicePostureChecks.read": "Allows the app to read device posture checks",
          "okta.devices.manage": "Allows the app to manage device status transitions and delete a device",
          "okta.devices.read": "Allows the app to read the existing device's profile and search devices",
          "okta.directories.groups.manage": "Allows the app to manage AD/LDAP groups for your Okta organization",
          "okta.directories.groups.read": "Allows the app to read AD/LDAP groups for your Okta organization",
          "okta.domains.manage": "Allows the app to manage custom Domains for your Okta organization",
          "okta.domains.read": "Allows the app to read information about custom Domains for your Okta organization",
          "okta.dr.manage": "Allows the app to manage disaster recovery",
          "okta.dr.read": "Allows the app to read the disaster recovery status",
          "okta.emailDomains.manage": "Allows the app to manage Email Domains for your Okta organization",
          "okta.emailDomains.read": "Allows the app to read information about Email Domains for your Okta organization",
          "okta.emailServers.manage": "Allows the app to manage Email Servers for your Okta organization",
          "okta.emailServers.read": "Allows the app to read information about Email Servers for your Okta organization",
          "okta.eventHooks.manage": "Allows the app to create and manage Event Hooks in your Okta organization",
          "okta.eventHooks.read": "Allows the app to read information about Event Hooks in your Okta organization",
          "okta.features.manage": "Allows the app to create and manage Features in your Okta organization",
          "okta.features.read": "Allows the app to read information about Features in your Okta organization",
          "okta.groups.manage": "Allows the app to create and manage groups in your Okta organization",
          "okta.groups.read": "Allows the app to read information about groups and their members in your Okta organization",
          "okta.identitySources.manage": "Allows the custom identity sources to manage user entities in your Okta organization",
          "okta.identitySources.read": "Allows to read session information for custom identity sources in your Okta organization",
          "okta.idps.manage": "Allows the app to create and manage Identity Providers in your Okta organization",
          "okta.idps.read": "Allows the app to read information about Identity Providers in your Okta organization",
          "okta.inlineHooks.manage": "Allows the app to create and manage Inline Hooks in your Okta organization",
          "okta.inlineHooks.read": "Allows the app to read information about Inline Hooks in your Okta organization",
          "okta.linkedObjects.manage": "Allows the app to manage linked object definitions in your Okta organization",
          "okta.linkedObjects.read": "Allows the app to read linked object definitions in your Okta organization",
          "okta.logStreams.manage": "Allows the app to create and manage log streams in your Okta organization",
          "okta.logStreams.read": "Allows the app to read information about log streams in your Okta organization",
          "okta.logs.read": "Allows the app to read information about System Log entries in your Okta organization",
          "okta.networkZones.manage": "Allows the app to create and manage Network Zones in your Okta organization",
          "okta.networkZones.read": "Allows the app to read Network Zones in your Okta organization",
          "okta.oauthIntegrations.manage": "Allows the app to create and manage API service Integration instances in your Okta organization",
          "okta.oauthIntegrations.read": "Allows the app to read API service Integration instances in your Okta organization",
          "okta.orgs.manage": "Allows the app to manage organization-specific details for your Okta organization",
          "okta.orgs.read": "Allows the app to read organization-specific details about your Okta organization",
          "okta.policies.manage": "Allows the app to manage policies in your Okta organization",
          "okta.policies.read": "Allows the app to read information about policies in your Okta organization",
          "okta.principalRateLimits.manage": "Allows the app to create and manage Principal Rate Limits in your Okta organization",
          "okta.principalRateLimits.read": "Allows the app to read information about Principal Rate Limits in your Okta organization",
          "okta.profileMappings.manage": "Allows the app to manage user profile mappings in your Okta organization",
          "okta.profileMappings.read": "Allows the app to read user profile mappings in your Okta organization",
          "okta.pushProviders.manage": "Allows the app to create and manage push notification providers such as APNs and FCM",
          "okta.pushProviders.read": "Allows the app to read push notification providers such as APNs and FCM",
          "okta.rateLimits.manage": "Allows the app to create and manage rate limits in your Okta organization",
          "okta.rateLimits.read": "Allows the app to read information about rate limits in your Okta organization",
          "okta.realmAssignments.manage": "Allows a user to manage realm assignments",
          "okta.realmAssignments.read": "Allows a user to read realm assignments",
          "okta.realms.manage": "Allows the app to create new realms and to manage their details",
          "okta.realms.read": "Allows the app to read the existing realms and their details",
          "okta.roles.manage": "Allows the app to manage administrative role assignments for users in your Okta organization. Delegated admins with this permission can only manage user credential fields and not the credential values themselves.",
          "okta.roles.read": "Allows the app to read administrative role assignments for users in your Okta organization. Delegated admins with this permission can only read user credential fields and not the credential values themselves.",
          "okta.schemas.manage": "Allows the app to create and manage Schemas in your Okta organization",
          "okta.schemas.read": "Allows the app to read information about Schemas in your Okta organization",
          "okta.securityEventsProviders.manage": "Allows the app to create and manage Security Events Providers in your Okta organization",
          "okta.securityEventsProviders.read": "Allows the app to read information about Security Events Providers in your Okta organization",
          "okta.serviceAccounts.manage": "Allows the app to manage service accounts in your Okta organization",
          "okta.serviceAccounts.okta.manage": "Allows the app to manage Okta managed user accounts in your Okta org",
          "okta.serviceAccounts.okta.read": "Allows the app to read Okta managed user accounts in your Okta org",
          "okta.serviceAccounts.read": "Allows the app to read service accounts in your Okta organization",
          "okta.sessions.manage": "Allows the app to manage all sessions in your Okta organization",
          "okta.sessions.read": "Allows the app to read all sessions in your Okta organization",
          "okta.templates.manage": "Allows the app to manage all custom templates in your Okta organization",
          "okta.templates.read": "Allows the app to read all custom templates in your Okta organization",
          "okta.threatInsights.manage": "Allows the app to manage all ThreatInsight configurations in your Okta organization",
          "okta.threatInsights.read": "Allows the app to read all ThreatInsight configurations in your Okta organization",
          "okta.trustedOrigins.manage": "Allows the app to manage all Trusted Origins in your Okta organization",
          "okta.trustedOrigins.read": "Allows the app to read all Trusted Origins in your Okta organization",
          "okta.uischemas.manage": "Allows the app to manage all the UI Schemas in your Okta organization",
          "okta.uischemas.read": "Allows the app to read all the UI Schemas in your Okta organization",
          "okta.userRisk.manage": "Allows the app to manage a user's risk in your Okta org",
          "okta.userRisk.read": "Allows the app to read a user's risk in your Okta org",
          "okta.userTypes.manage": "Allows the app to manage user types in your Okta org",
          "okta.userTypes.read": "Allows the app to read user types in your Okta org",
          "okta.users.manage": "Allows the app to create new users and to manage all users' profile and credentials information",
          "okta.users.read": "Allows the app to read the existing users' profiles and credentials",
          "ssf.manage": "Allows the app to create and manage Shared Signals Framework (SSF) in your Okta organization",
          "ssf.read": "Allows the app to read information about Shared Signals Framework (SSF) in your Okta organization"
        }
      }
    }
  }
}

Each operation lists its security requirements. An empty security array permits an unauthenticated request. Use the scheme and headers declared for the selected contract.

Operations

GET /api/v1/users/{id}

Retrieve a user

Retrieves a user from your Okta org. You can substitute `me` for the `id` to fetch the current user linked to an API token or session cookie. * The request returns the user linked to the API token that is specified in the Authorization header, not the user linked to the active session. Details of the admin user who granted the API token is returned. * When the end user has an active Okta session, it is typically a CORS request from the browser. Therefore, it's possible to retrieve the current user without the Authorization header. When fetching a user by `login` or `login shortname`, [URL encode](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) the request parameter to ensure that special characters are escaped properly. Logins with a `/` character can only be fetched by `id` due to URL issues with escaping the `/` character. If you don't know a user's ID, you can use the [List all users](/openapi/okta-management/management/user/listusers) endpoint to find it. > **Note:** Some browsers block third-party cookies by default, which disrupts Okta functionality in certain flows. See [Mitigate the impact of third-party cookie deprecation](https://help.okta.com/okta_help.htm?type=oie&id=ext-third-party-cookies).

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.users.read"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "Retrieve a user",
  "description": "Retrieves a user from your Okta org.\n\nYou can substitute `me` for the `id` to fetch the current user linked to an API token or session cookie.\n * The request returns the user linked to the API token that is specified in the Authorization header, not the user linked to the active session. Details of the admin user who granted the API token is returned.\n * When the end user has an active Okta session, it is typically a CORS request from the browser. Therefore, it's possible to retrieve the current user without the Authorization header.\n\nWhen fetching a user by `login` or `login shortname`, [URL encode](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) the request parameter to ensure that special characters are escaped properly. Logins with a `/` character can only be fetched by `id` due to URL issues with escaping the `/` character. If you don't know a user's ID, you can use the [List all users](/openapi/okta-management/management/user/listusers) endpoint to find it.\n\n> **Note:** Some browsers block third-party cookies by default, which disrupts Okta functionality in certain flows. See [Mitigate the impact of third-party cookie deprecation](https://help.okta.com/okta_help.htm?type=oie&id=ext-third-party-cookies).",
  "operationId": "getUser",
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "Etag": {
          "description": "An HTTP entity tag (`ETag`) is an identifier for a specific version of a resource. See [Conditional Requests and Entity Tags](/#conditional-requests-and-entity-tags).",
          "schema": {
            "type": "string"
          },
          "example": "W/\"1234567890abcdef\""
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UserGetSingleton"
          },
          "examples": {
            "GetUserExample": {
              "$ref": "#/components/examples/user-example"
            }
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Not Found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.users.read"
      ]
    }
  ],
  "tags": [
    "User"
  ],
  "x-okta-lifecycle": {
    "isCorsEnabled": true,
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  }
}

POST /api/v1/users/{id}/lifecycle/unlock

Unlock a user

Unlocks a user with a `LOCKED_OUT` status or unlocks a user with an `ACTIVE` status that's blocked from unknown devices. Unlocked users have an `ACTIVE` status and can sign in with their current password. > **Note:** This operation works with Okta-sourced users. It doesn't support directory-sourced accounts such as Active Directory.

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.users.manage"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "Unlock a user",
  "description": "Unlocks a user with a `LOCKED_OUT` status or unlocks a user with an `ACTIVE` status that's blocked from unknown devices. Unlocked users have an `ACTIVE` status and can sign in with their current password.\n> **Note:** This operation works with Okta-sourced users. It doesn't support directory-sourced accounts such as Active Directory.",
  "operationId": "unlockUser",
  "responses": {
    "200": {
      "description": "Success",
      "content": {}
    },
    "403": {
      "$ref": "#/components/responses/ErrorAccessDenied403"
    },
    "404": {
      "$ref": "#/components/responses/ErrorResourceNotFound404"
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.users.manage"
      ]
    }
  ],
  "tags": [
    "UserLifecycle"
  ],
  "x-okta-lifecycle": {
    "isCorsEnabled": true,
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  }
}

POST /api/v1/users/{id}/lifecycle/expire_password

Expire the password

Expires the password. This operation transitions the user status to `PASSWORD_EXPIRED` so that the user must change their password the next time that they sign in. <br> If you have integrated Okta with your on-premises Active Directory (AD), then setting a user's password as expired in Okta also expires the password in AD. When the user tries to sign in to Okta, delegated authentication finds the password-expired status in AD, and the user is presented with the password-expired page where they can change their password. > **Note:** The Okta account management policy doesn't support the `/users/{id}/lifecycle/expire_password` endpoint. See [Configure an Okta account management policy](https://developer.okta.com/docs/guides/okta-account-management-policy/main/).

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.users.manage"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "Expire the password",
  "description": "Expires the password. This operation transitions the user status to `PASSWORD_EXPIRED` so that the user must change their password the next time that they sign in.\n<br>\nIf you have integrated Okta with your on-premises Active Directory (AD), then setting a user's password as expired in Okta also expires the password in AD.\nWhen the user tries to sign in to Okta, delegated authentication finds the password-expired status in AD,\nand the user is presented with the password-expired page where they can change their password.\n\n> **Note:** The Okta account management policy doesn't support the `/users/{id}/lifecycle/expire_password` endpoint. See [Configure an Okta account management policy](https://developer.okta.com/docs/guides/okta-account-management-policy/main/).",
  "operationId": "expirePassword",
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/User"
          },
          "examples": {
            "Expire password response": {
              "$ref": "#/components/examples/ExpirePwdResponse"
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/ErrorAccessDenied403"
    },
    "404": {
      "$ref": "#/components/responses/ErrorResourceNotFound404"
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.users.manage"
      ]
    }
  ],
  "tags": [
    "UserCred"
  ],
  "x-okta-lifecycle": {
    "isCorsEnabled": true,
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  }
}

POST /api/v1/users/{userId}/credentials/forgot_password

Start forgot password flow

Starts the forgot password flow. Generates a one-time token (OTT) that you can use to reset a user's password. The user must validate their security question's answer when visiting the reset link. Perform this operation only on users with an `ACTIVE` status and a valid [recovery question credential](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/createUser!path=credentials/recovery_question&t=request). > **Note:** If you have migrated to Identity Engine, you can allow users to recover passwords with any enrolled MFA authenticator. See [Self-service account recovery](https://help.okta.com/oie/en-us/content/topics/identity-engine/authenticators/configure-sspr.htm?cshid=ext-config-sspr). If an email address is associated with multiple users, keep in mind the following to ensure a successful password recovery lookup: * Okta no longer includes deactivated users in the lookup. * The lookup searches sign-in IDs first, then primary email addresses, and then secondary email addresses. If `sendEmail` is `false`, returns a link for the user to reset their password. This operation doesn't affect the status of the user.

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.users.manage"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathUserId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "Start forgot password flow",
  "description": "Starts the forgot password flow.\n\nGenerates a one-time token (OTT) that you can use to reset a user's password.\n\nThe user must validate their security question's answer when visiting the reset link. Perform this operation only on users with an `ACTIVE` status and\na valid [recovery question credential](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/createUser!path=credentials/recovery_question&t=request).\n\n> **Note:** If you have migrated to Identity Engine, you can allow users to recover passwords with any enrolled MFA authenticator. See [Self-service account recovery](https://help.okta.com/oie/en-us/content/topics/identity-engine/authenticators/configure-sspr.htm?cshid=ext-config-sspr).\n\nIf an email address is associated with multiple users, keep in mind the following to ensure a successful password recovery lookup:\n  * Okta no longer includes deactivated users in the lookup.\n  * The lookup searches sign-in IDs first, then primary email addresses, and then secondary email addresses.\n\nIf `sendEmail` is `false`, returns a link for the user to reset their password. This operation doesn't affect the status of the user.",
  "operationId": "forgotPassword",
  "parameters": [
    {
      "name": "sendEmail",
      "in": "query",
      "description": "Sends a forgot password email to the user if `true`",
      "required": false,
      "schema": {
        "type": "boolean",
        "default": true
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Reset URL",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ForgotPasswordResponse"
          },
          "examples": {
            "Forgot password response": {
              "$ref": "#/components/examples/ForgotPwdResponse"
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/ErrorAccessDenied403"
    },
    "404": {
      "$ref": "#/components/responses/ErrorResourceNotFound404"
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.users.manage"
      ]
    }
  ],
  "tags": [
    "UserCred"
  ],
  "x-okta-lifecycle": {
    "isCorsEnabled": true,
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  }
}

GET /api/v1/users/{id}/groups

List all groups

Lists all groups of which the user is a member > **Note:** To list all groups in your org, use the [List all groups endpoints in the Groups API](/openapi/okta-management/management/group/listgroups).

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.users.read"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "List all groups",
  "description": "Lists all groups of which the user is a member\n> **Note:** To list all groups in your org, use the [List all groups endpoints in the Groups API](/openapi/okta-management/management/group/listgroups).",
  "operationId": "listUserGroups",
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Group"
            }
          },
          "examples": {
            "List user groups": {
              "$ref": "#/components/examples/ListUserGroups"
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/ErrorAccessDenied403"
    },
    "404": {
      "$ref": "#/components/responses/ErrorResourceNotFound404"
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.users.read"
      ]
    }
  ],
  "tags": [
    "UserResources"
  ],
  "x-okta-lifecycle": {
    "isCorsEnabled": true,
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  }
}

PUT /api/v1/groups/{groupId}/users/{userId}

Assign a user to a group

Assigns a user to a group with the `OKTA_GROUP` type. > **Note:** You only can modify memberships for groups of the `OKTA_GROUP` type. App imports are responsible for managing group memberships for groups of the `APP_GROUP` type, such as Active Directory groups.

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.groups.manage"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathGroupId"
    },
    {
      "$ref": "#/components/parameters/pathUserId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "Assign a user to a group",
  "description": "Assigns a user to a group with the `OKTA_GROUP` type.\n> **Note:** You only can modify memberships for groups of the `OKTA_GROUP` type. App imports are responsible for managing group memberships for groups of the `APP_GROUP` type, such as Active Directory groups.",
  "operationId": "assignUserToGroup",
  "responses": {
    "204": {
      "description": "No Content",
      "content": {}
    },
    "403": {
      "$ref": "#/components/responses/ErrorAccessDenied403"
    },
    "404": {
      "$ref": "#/components/responses/ErrorResourceNotFound404"
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.groups.manage"
      ]
    }
  ],
  "tags": [
    "Group"
  ],
  "x-okta-lifecycle": {
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  }
}

GET /api/v1/groups/{groupId}/users

List all member users

Lists all users that are a member of a group. The default user limit is set to a very high number due to historical reasons that are no longer valid for most orgs. This will change in a future version of this API. The recommended page limit is now `limit=200`.

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.groups.read"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathGroupId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "List all member users",
  "description": "Lists all users that are a member of a group.\nThe default user limit is set to a very high number due to historical reasons that are no longer valid for most orgs. This will change in a future version of this API. The recommended page limit is now `limit=200`.",
  "operationId": "listGroupUsers",
  "parameters": [
    {
      "$ref": "#/components/parameters/queryAfter"
    },
    {
      "name": "limit",
      "in": "query",
      "description": "Specifies the number of user results in a page",
      "schema": {
        "type": "integer",
        "format": "int32",
        "default": 1000
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/User"
            }
          },
          "examples": {
            "ListMemberUserResponse": {
              "$ref": "#/components/examples/ListUsersResponse"
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/ErrorAccessDenied403"
    },
    "404": {
      "$ref": "#/components/responses/ErrorResourceNotFound404"
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.groups.read"
      ]
    }
  ],
  "tags": [
    "Group"
  ],
  "x-okta-lifecycle": {
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  }
}

POST /api/v1/users/{id}/lifecycle/forgot_password

Start forgot password flow

Starts the forgot password flow for a user. This path is called by Okta's own clients and is listed as a live route in Okta's published rate-limit table, but it is absent from the published OpenAPI document. PurpleSuite serves it from the same handler as `POST /api/v1/users/{userId}/credentials/forgot_password`.

Authentication

[
  {
    "apiToken": []
  },
  {
    "oauth2": [
      "okta.users.manage"
    ]
  }
]

Path-level parameters and metadata

{
  "parameters": [
    {
      "$ref": "#/components/parameters/pathId"
    }
  ]
}

Request, responses and operation details

{
  "summary": "Start forgot password flow",
  "description": "Starts the forgot password flow for a user. This path is called by Okta's own clients and is listed as a live route in Okta's published rate-limit table, but it is absent from the published OpenAPI document. PurpleSuite serves it from the same handler as `POST /api/v1/users/{userId}/credentials/forgot_password`.",
  "operationId": "forgotPasswordLifecycle",
  "parameters": [
    {
      "name": "sendEmail",
      "in": "query",
      "description": "Sends a forgot password email to the user if `true`",
      "required": false,
      "schema": {
        "type": "boolean",
        "default": true
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Reset URL",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ForgotPasswordResponse"
          },
          "examples": {
            "Forgot password response": {
              "$ref": "#/components/examples/ForgotPwdResponse"
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/ErrorAccessDenied403"
    },
    "404": {
      "$ref": "#/components/responses/ErrorResourceNotFound404"
    },
    "429": {
      "$ref": "#/components/responses/ErrorTooManyRequests429"
    }
  },
  "security": [
    {
      "apiToken": []
    },
    {
      "oauth2": [
        "okta.users.manage"
      ]
    }
  ],
  "tags": [
    "UserCred"
  ],
  "x-okta-lifecycle": {
    "isCorsEnabled": true,
    "lifecycle": "GA",
    "isGenerallyAvailable": true
  },
  "x-purplesuite-classification": "disclosed-addition"
}

Schemas and reusable components

examples

ErrorAccessDenied

{
  "summary": "Access Denied",
  "value": {
    "errorCode": "E0000006",
    "errorSummary": "You do not have permission to perform the requested action",
    "errorLink": "E0000006",
    "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
    "errorCauses": []
  }
}

ErrorResourceNotFound

{
  "summary": "Resource Not Found",
  "value": {
    "errorCode": "E0000007",
    "errorSummary": "Not found: {0}",
    "errorLink": "E0000007",
    "errorId": "sampleMlLvGUj_YD5v16vkYWY",
    "errorCauses": []
  }
}

ErrorTooManyRequests

{
  "summary": "Too Many Requests",
  "value": {
    "errorCode": "E0000047",
    "errorSummary": "API call exceeded rate limit due to too many requests.",
    "errorLink": "E0000047",
    "errorId": "sampleQPivGUj_ND5v78vbYWW",
    "errorCauses": []
  }
}

ExpirePwdResponse

{
  "value": {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "PASSWORD_EXPIRED",
    "created": "2013-06-24T16:39:18.000Z",
    "activated": "2013-06-24T16:39:19.000Z",
    "statusChanged": "2013-06-24T16:39:19.000Z",
    "lastLogin": "2013-06-24T17:39:19.000Z",
    "lastUpdated": "2013-06-27T16:35:28.000Z",
    "passwordChanged": "2013-06-24T16:39:19.000Z",
    "profile": {
      "firstName": "Isaac",
      "lastName": "Brock",
      "email": "isaac.brock@example.com",
      "login": "isaac.brock@example.com",
      "mobilePhone": "555-415-1337"
    },
    "credentials": {
      "password": {},
      "recovery_question": {
        "question": "Who's a major player in the cowboy scene?"
      },
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "resetPassword": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_password"
      },
      "resetFactors": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/reset_factors"
      },
      "expirePassword": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/expire_password"
      },
      "forgotPassword": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/forgot_password"
      },
      "changeRecoveryQuestion": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_recovery_question"
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/lifecycle/deactivate"
      },
      "changePassword": {
        "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/credentials/change_password"
      }
    }
  }
}

ForgotPwdResponse

{
  "value": {
    "resetPasswordUrl": "https://{yourOktaDomain}/signin/reset-password/XE6wE17zmphl3KqAPFxO"
  }
}

ListUserGroups

{
  "value": [
    {
      "id": "0gabcd1234",
      "profile": {
        "name": "Cloud app users",
        "description": "Users can access cloud apps"
      }
    },
    {
      "id": "0gefgh5678",
      "profile": {
        "name": "Internal app users",
        "description": "Users can access internal apps"
      }
    }
  ]
}

ListUsersResponse

{
  "summary": "List all users",
  "value": [
    {
      "id": "00u118oQYT4TBTemp0g4",
      "status": "ACTIVE",
      "created": "2022-04-04T15:56:05.000Z",
      "activated": null,
      "statusChanged": null,
      "lastLogin": "2022-05-04T19:50:52.000Z",
      "lastUpdated": "2022-05-05T18:15:44.000Z",
      "passwordChanged": "2022-04-04T16:00:22.000Z",
      "type": {
        "id": "oty1162QAr8hJjTaq0g4"
      },
      "profile": {
        "firstName": "Alice",
        "lastName": "Smith",
        "mobilePhone": null,
        "secondEmail": null,
        "login": "alice.smith@example.com",
        "email": "alice.smith@example.com"
      },
      "credentials": {
        "password": {},
        "provider": {
          "type": "OKTA",
          "name": "OKTA"
        }
      },
      "_links": {
        "self": {
          "href": "http://your-subdomain.okta.com/api/v1/users/00u118oQYT4TBGuay0g4"
        }
      }
    }
  ]
}

user-example

{
  "summary": "User example",
  "value": {
    "id": "00ub0oNGTSWTBKOLGLNR",
    "status": "ACTIVE",
    "created": "2013-06-24T16:39:18.000Z",
    "activated": "2013-06-24T16:39:19.000Z",
    "statusChanged": "2013-06-24T16:39:19.000Z",
    "lastLogin": "2013-06-24T17:39:19.000Z",
    "lastUpdated": "2013-07-02T21:36:25.344Z",
    "passwordChanged": "2013-07-02T21:36:25.344Z",
    "profile": {
      "login": "isaac.brock@example.com",
      "firstName": "Isaac",
      "lastName": "Brock",
      "nickName": "issac",
      "displayName": "Isaac Brock",
      "email": "isaac.brock@example.com",
      "secondEmail": "isaac@example.org",
      "profileUrl": "http://www.example.com/profile",
      "preferredLanguage": "en-US",
      "userType": "Employee",
      "organization": "Okta",
      "title": "Director",
      "division": "R&D",
      "department": "Engineering",
      "costCenter": "10",
      "employeeNumber": "187",
      "mobilePhone": "+1-555-415-1337",
      "primaryPhone": "+1-555-514-1337",
      "streetAddress": "301 Brannan St.",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94107",
      "countryCode": "US"
    },
    "credentials": {
      "password": {},
      "recovery_question": {
        "question": "What's my childhood elementary school?"
      },
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00u1f96ECLNVOKVMUSEA"
      }
    }
  }
}

parameters

pathGroupId

{
  "name": "groupId",
  "description": "The `id` of the group",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "example": "00g1emaKYZTWRYYRRTSK"
  }
}

pathId

{
  "name": "id",
  "description": "An ID, login, or login shortname (as long as the shortname is unambiguous) of an existing Okta user",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  }
}

pathUserId

{
  "name": "userId",
  "description": "ID of an existing Okta user",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "example": "00ub0oNGTSWTBKOLGLNR"
  }
}

queryAfter

{
  "name": "after",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the `Link` response header. See [Pagination](https://developer.okta.com/docs/api/#pagination) and [Link header](https://developer.okta.com/docs/api/#link-header)."
}

responses

ErrorAccessDenied403

{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      },
      "examples": {
        "AccessDenied": {
          "$ref": "#/components/examples/ErrorAccessDenied"
        }
      }
    }
  }
}

ErrorResourceNotFound404

{
  "description": "Not Found",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      },
      "examples": {
        "ResourceNotFound": {
          "$ref": "#/components/examples/ErrorResourceNotFound"
        }
      }
    }
  }
}

ErrorTooManyRequests429

{
  "description": "Too Many Requests",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      },
      "examples": {
        "TooManyRequests": {
          "$ref": "#/components/examples/ErrorTooManyRequests"
        }
      }
    }
  }
}

schemas

AuthenticationProvider

{
  "description": "Specifies the authentication provider that validates the user's password credential. The user's current provider is managed by the **Delegated Authentication** settings for your org. The provider object is **read-only**.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the authentication provider",
      "readOnly": true,
      "example": "OKTA"
    },
    "type": {
      "$ref": "#/components/schemas/AuthenticationProviderType"
    }
  },
  "readOnly": true
}

AuthenticationProviderType

{
  "description": "The type of authentication provider",
  "type": "string",
  "enum": [
    "ACTIVE_DIRECTORY",
    "FEDERATION",
    "IMPORT",
    "LDAP",
    "OKTA",
    "SOCIAL"
  ],
  "x-enumDescriptions": {
    "ACTIVE_DIRECTORY": "Specifies the Microsoft Active Directory instance name as the `name` property",
    "FEDERATION": "Specifies a federated identity provider (such as an SAML IdP) that validates the user's password credentials. Doesn't support a `password` or `recovery question` credential. The user must authenticate through a trusted identity provider.",
    "IMPORT": "Specifies a hashed password that was imported from an external source",
    "LDAP": "Specifies the LDAP directory instance name as the `name` property",
    "OKTA": "Specifies the Okta identity provider",
    "SOCIAL": "Specifies an OIDC or third-party social identity provider. Doesn't support a `password` or `recovery question` credential. The user must authenticate through a trusted identity provider."
  },
  "readOnly": true
}

DigestAlgorithm

{
  "description": "Algorithm used to generate the key. Only required for the PBKDF2 algorithm.",
  "type": "string",
  "enum": [
    "SHA256_HMAC",
    "SHA512_HMAC"
  ]
}

Error

{
  "title": "Error",
  "type": "object",
  "properties": {
    "errorCauses": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ErrorCause"
      }
    },
    "errorCode": {
      "type": "string",
      "description": "An Okta code for this type of error"
    },
    "errorId": {
      "type": "string",
      "description": "A unique identifier for this error. This can be used by Okta Support to help with troubleshooting."
    },
    "errorLink": {
      "type": "string",
      "description": "An Okta code for this type of error"
    },
    "errorSummary": {
      "type": "string",
      "description": "A short description of what caused this error. Sometimes this contains dynamically-generated information about your specific error."
    }
  }
}

ErrorCause

{
  "type": "object",
  "properties": {
    "errorSummary": {
      "type": "string"
    }
  }
}

ForgotPasswordResponse

{
  "type": "object",
  "properties": {
    "resetPasswordUrl": {
      "type": "string",
      "readOnly": true
    }
  }
}

Group

{
  "x-okta-ignore-redocly-rules-for-sdk": true,
  "type": "object",
  "properties": {
    "created": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "Timestamp when the group was created"
    },
    "id": {
      "type": "string",
      "readOnly": true,
      "example": "0gabcd1234",
      "description": "Unique ID for the group"
    },
    "lastMembershipUpdated": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "Timestamp when the groups memberships were last updated"
    },
    "lastUpdated": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "Timestamp when the group's profile was last updated"
    },
    "objectClass": {
      "type": "array",
      "readOnly": true,
      "description": "Determines the group's `profile`",
      "items": {
        "type": "string"
      }
    },
    "profile": {
      "$ref": "#/components/schemas/GroupProfile"
    },
    "type": {
      "$ref": "#/components/schemas/GroupType"
    },
    "_embedded": {
      "type": "object",
      "description": "Embedded resources related to the group",
      "readOnly": true,
      "properties": {
        "stats": {
          "description": "Statistics about the group",
          "type": "object",
          "properties": {
            "usersCount": {
              "type": "integer",
              "format": "int32",
              "description": "Number of users in the group"
            },
            "appsCount": {
              "type": "integer",
              "format": "int32",
              "description": "Number of apps associated with the group"
            },
            "groupPushMappingsCount": {
              "type": "integer",
              "format": "int32",
              "description": "Number of group push mappings associated with the group"
            },
            "hasAdminPrivlege": {
              "type": "boolean",
              "description": "Indicates if the group has admin privileges via a group-level role assignment"
            }
          }
        },
        "app": {
          "description": "If the group is sourced from an app, this object contains information about that app",
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The ID of the `AppInstance`"
            },
            "name": {
              "type": "string",
              "description": "The name of the `AppInstance`"
            },
            "label": {
              "type": "string",
              "description": "The user-facing display name of the `AppInstance`"
            },
            "signOnMode": {
              "type": "string",
              "description": "The configured sign-on mode for the `AppInstance`",
              "example": "SAML_1_1"
            }
          }
        }
      }
    },
    "_links": {
      "description": "[Discoverable resources](/openapi/okta-management/management/group/listgroups#group/listgroups/t=response&c=200&path=_links/source) related to the group",
      "allOf": [
        {
          "$ref": "#/components/schemas/LinksSelf"
        },
        {
          "properties": {
            "apps": {
              "$ref": "#/components/schemas/HrefObject"
            },
            "logo": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/HrefObject"
              }
            },
            "source": {
              "$ref": "#/components/schemas/HrefObject"
            },
            "users": {
              "$ref": "#/components/schemas/HrefObject"
            }
          }
        }
      ]
    }
  }
}

GroupProfile

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/OktaUserGroupProfile"
    },
    {
      "$ref": "#/components/schemas/OktaActiveDirectoryGroupProfile"
    }
  ]
}

GroupType

{
  "description": "Determines how a group's profile and memberships are managed",
  "type": "string",
  "enum": [
    "APP_GROUP",
    "BUILT_IN",
    "OKTA_GROUP"
  ],
  "x-enumDescriptions": {
    "APP_GROUP": "Group profile and memberships are imported and must be managed within the app (such as Active Directory or LDAP) that imported the group",
    "BUILT_IN": "Group profile and memberships are managed by Okta and can't be modified",
    "OKTA_GROUP": "Group profile and memberships are directly managed in Okta via static assignments or indirectly through group rules"
  }
}

HrefHints

{
  "description": "Describes allowed HTTP verbs for the `href`",
  "type": "object",
  "properties": {
    "allow": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/HttpMethod"
      }
    }
  }
}

HrefObject

{
  "x-okta-ignore-redocly-rules-for-sdk": true,
  "title": "Link Object",
  "additionalProperties": true,
  "type": "object",
  "properties": {
    "hints": {
      "$ref": "#/components/schemas/HrefHints",
      "readOnly": true
    },
    "href": {
      "type": "string",
      "description": "Link URI"
    },
    "name": {
      "type": "string",
      "description": "Link name",
      "readOnly": true
    },
    "templated": {
      "type": "boolean",
      "description": "Indicates whether the link object's `href` property is a URI template.",
      "readOnly": true
    },
    "type": {
      "type": "string",
      "description": "The media type of the link. If omitted, it is implicitly `application/json`.",
      "readOnly": true
    }
  },
  "required": [
    "href"
  ]
}

HttpMethod

{
  "type": "string",
  "enum": [
    "DELETE",
    "GET",
    "POST",
    "PUT"
  ]
}

LinksSelf

{
  "description": "Specifies link relations (see [Web Linking](https://www.rfc-editor.org/rfc/rfc8288)) available using the [JSON Hypertext Application Language](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06) specification. This object is used for dynamic discovery of related resources and lifecycle operations.",
  "type": "object",
  "properties": {
    "self": {
      "$ref": "#/components/schemas/HrefObjectSelfLink"
    }
  },
  "readOnly": true
}

OktaActiveDirectoryGroupProfile

{
  "description": "Profile for a group that is imported from Active Directory.\n\nThe `objectClass` for such groups is `okta:windows_security_principal`.\n\nYou can extend group profiles with custom properties, but you must first add the properties to the group profile schema before you can reference them. Use the Profile Editor in the Admin Console or the [Schemas API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Schema/) to manage schema extensions.\n\nCustom properties can contain HTML tags. It is the client's responsibility to escape or encode this data before displaying it. Use [best-practices](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) to prevent cross-site scripting.",
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "example": "All users in the engineering department",
      "description": "Description of the Windows group"
    },
    "dn": {
      "type": "string",
      "example": "CN=West Coast users,OU=West Coast,DC=example,DC=com",
      "description": "The distinguished name of the Windows group"
    },
    "externalId": {
      "type": "string",
      "example": "VKzYZ1C+IkSZxIWlrW5ITg==",
      "description": "Base-64 encoded GUID (`objectGUID`) of the Windows group"
    },
    "name": {
      "type": "string",
      "example": "West Coast users",
      "description": "Name of the Windows group"
    },
    "samAccountName": {
      "type": "string",
      "example": "West Coast users",
      "description": "Pre-Windows 2000 name of the Windows group"
    },
    "windowsDomainQualifiedName": {
      "type": "string",
      "example": "EXAMPLE\\\\West Coast users",
      "description": "Fully qualified name of the Windows group"
    }
  }
}

OktaUserGroupProfile

{
  "description": "Profile for any group that is not imported from Active Directory. Specifies the standard\nand custom profile properties for a group.\n\nThe `objectClass` for these groups is `okta:user_group`.\n\nYou can extend group profiles with custom properties, but you must first add the properties to the group profile schema before you can reference them. Use the Profile Editor in the Admin Console or the [Schemas API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Schema/) to manage schema extensions.\n\nCustom properties can contain HTML tags. It is the client's responsibility to escape or encode this data before displaying it. Use [best-practices](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) to prevent cross-site scripting.",
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "example": "All users West of The Rockies",
      "description": "Description of the group"
    },
    "name": {
      "type": "string",
      "example": "West Coast users",
      "description": "Name of the group"
    }
  },
  "x-okta-extensible": true
}

PasswordCredential

{
  "description": "Specifies a password for a user.\n\nWhen a user has a valid password, imported hashed password, or password hook, and a response object contains\na password credential, then the password object is a bare object without the value property defined (for example, `password: {}`). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator:  **Security** > **Authenticators** > **Password** (or for Okta Classic orgs, use **Security** > **Authentication** > **Password**).\n\nFor information on defaults and configuring your password policies, see [Configure the password authenticator](https://help.okta.com/okta_help.htm?type=oie&id=ext-configure-password) in the help documentation.",
  "type": "object",
  "properties": {
    "hash": {
      "$ref": "#/components/schemas/PasswordCredentialHash"
    },
    "hook": {
      "$ref": "#/components/schemas/PasswordCredentialHook"
    },
    "value": {
      "type": "string",
      "writeOnly": true,
      "description": "Specifies the password for a user. The password policy validates this password.",
      "format": "password",
      "example": "pa$$word"
    }
  }
}

PasswordCredentialHash

{
  "description": "Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly\nfrom some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import.\n A hashed password may be specified in a password object when creating or updating a user, but not for other operations.\n See the [Create user with imported hashed password](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#create-user-with-imported-hashed-password) description. When you update a user with a hashed password, the user must be in the `STAGED` status.",
  "type": "object",
  "properties": {
    "algorithm": {
      "$ref": "#/components/schemas/PasswordCredentialHashAlgorithm"
    },
    "digestAlgorithm": {
      "$ref": "#/components/schemas/DigestAlgorithm"
    },
    "iterationCount": {
      "type": "integer",
      "description": "The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm."
    },
    "keySize": {
      "type": "integer",
      "description": "Size of the derived key in bytes. Only required for PBKDF2 algorithm."
    },
    "salt": {
      "description": "Only required for salted hashes. For BCRYPT, this specifies Radix-64 as the encoded salt used to generate the hash,\nwhich must be 22 characters long. For other salted hashes, this specifies the Base64-encoded salt used to\ngenerate the hash.",
      "type": "string"
    },
    "saltOrder": {
      "type": "string",
      "description": "Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms."
    },
    "value": {
      "description": "For SHA-512, SHA-256, SHA-1, MD5, and PBKDF2, this is the actual base64-encoded hash of the password (and salt, if used).\nThis is the Base64-encoded `value` of the SHA-512/SHA-256/SHA-1/MD5/PBKDF2 digest that was computed by either pre-fixing or post-fixing\nthe `salt` to the `password`, depending on the `saltOrder`. If a `salt` was not used in the `source` system, then this should just be\nthe Base64-encoded `value` of the password's SHA-512/SHA-256/SHA-1/MD5/PBKDF2 digest. For BCRYPT, this is the actual Radix-64 encoded hashed password.",
      "type": "string"
    },
    "workFactor": {
      "type": "integer",
      "description": "Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.",
      "minimum": 1,
      "maximum": 20
    }
  }
}

PasswordCredentialHashAlgorithm

{
  "description": "The algorithm used to generate the hash using the password (and salt, when applicable).",
  "type": "string",
  "enum": [
    "BCRYPT",
    "MD5",
    "PBKDF2",
    "SHA-1",
    "SHA-256",
    "SHA-512"
  ]
}

PasswordCredentialHook

{
  "description": "Specify a [password import inline hook](/openapi/okta-management/management/tags/inlinehook/createpasswordimportinlinehook) to trigger verification of the user's password the first time the user signs in. This allows an existing password to be imported into Okta directly from some other store.",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "The type of password inline hook. Currently, must be set to default."
    }
  }
}

RecoveryQuestionCredential

{
  "description": "Specifies a secret question and answer that's validated (case insensitive) when a user forgets their\npassword or unlocks their account. The answer property is write-only.",
  "type": "object",
  "properties": {
    "answer": {
      "type": "string",
      "description": "The answer to the recovery question",
      "minimum": 1,
      "maximum": 100,
      "writeOnly": true,
      "example": "se7en"
    },
    "question": {
      "type": "string",
      "description": "The recovery question",
      "minimum": 1,
      "maximum": 100,
      "example": "what is your favourite movie?"
    }
  }
}

User

{
  "x-okta-ignore-redocly-rules-for-sdk": true,
  "type": "object",
  "properties": {
    "activated": {
      "type": "string",
      "description": "The timestamp when the user status transitioned to `ACTIVE`",
      "format": "date-time",
      "readOnly": true,
      "nullable": true
    },
    "created": {
      "type": "string",
      "description": "The timestamp when the user was created",
      "format": "date-time",
      "readOnly": true
    },
    "credentials": {
      "$ref": "#/components/schemas/UserCredentials"
    },
    "id": {
      "type": "string",
      "description": "The unique key for the user",
      "readOnly": true
    },
    "lastLogin": {
      "type": "string",
      "description": "The timestamp of the last login",
      "format": "date-time",
      "readOnly": true,
      "nullable": true
    },
    "lastUpdated": {
      "type": "string",
      "description": "The timestamp when the user was last updated",
      "format": "date-time",
      "readOnly": true
    },
    "passwordChanged": {
      "type": "string",
      "description": "The timestamp when the user's password was last updated",
      "format": "date-time",
      "readOnly": true,
      "nullable": true
    },
    "profile": {
      "$ref": "#/components/schemas/UserProfile"
    },
    "realmId": {
      "type": "string",
      "description": "The ID of the realm in which the user is residing. See [Realms](/openapi/okta-management/management/tags/realm).",
      "example": "guo1bfiNtSnZYILxO0g4",
      "readOnly": true
    },
    "status": {
      "$ref": "#/components/schemas/UserStatus"
    },
    "statusChanged": {
      "type": "string",
      "description": "The timestamp when the status of the user last changed",
      "format": "date-time",
      "readOnly": true,
      "nullable": true
    },
    "transitioningToStatus": {
      "type": "string",
      "description": "The target status of an in-progress asynchronous status transition. This property is only returned if the user's state is transitioning.",
      "readOnly": true,
      "nullable": true,
      "enum": [
        "ACTIVE",
        "DEPROVISIONED",
        "PROVISIONED"
      ]
    },
    "type": {
      "type": "object",
      "description": "The user type that determines the schema for the user's profile. The `type` property is a map that identifies the [User Types](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserType/#tag/UserType).\n\nCurrently it contains a single element, `id`. It can be specified when creating a new user, and can be updated by an admin on a full replace of an existing user (but not a partial update).",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the user type"
        }
      }
    },
    "_embedded": {
      "type": "object",
      "description": "Embedded resources related to the user using the [JSON Hypertext Application Language](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06) specification",
      "additionalProperties": {
        "type": "object",
        "properties": {}
      },
      "readOnly": true
    },
    "_links": {
      "description": "Specifies link relations (see [Web Linking](https://datatracker.ietf.org/doc/html/rfc8288) available for the current status of a user.\nThe links object is used for dynamic discovery of related resources, lifecycle operations, and credential operations. The links object is read-only.\n\nFor an individual user result, the links object contains a full set of link relations available for that user as determined by your policies.\nFor a collection of users, the links object contains only the `self` link. Operations that return a collection of users include [List all users](https://developer.okta.com/docs/api/openapi/okta-management/management/user/listusers) and [List all group member users](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/listGroupUsers).",
      "allOf": [
        {
          "$ref": "#/components/schemas/LinksSelf"
        },
        {
          "type": "object",
          "properties": {
            "self": {
              "description": "URL to the individual user",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "activate": {
              "description": "URL to activate the user",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "resetPassword": {
              "description": "URL to reset the user's password",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "resetFactors": {
              "description": "URL to reset the user's factors",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "expirePassword": {
              "description": "URL to expire the user's password",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "forgotPassword": {
              "description": "URL to initiate a forgot password operation",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "changeRecoveryQuestion": {
              "description": "URL to change the user's recovery question",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "deactivate": {
              "description": "URL to deactivate a user",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "reactivate": {
              "description": "URL to reactivate the user",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "changePassword": {
              "description": "URL to change the user's password",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "schema": {
              "description": "URL to the user's profile schema",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "suspend": {
              "description": "URL to suspend the user",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "unsuspend": {
              "description": "URL to unsuspend the user",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "unlock": {
              "description": "URL to unlock the locked-out user",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            },
            "type": {
              "description": "URL to the user type",
              "allOf": [
                {
                  "$ref": "#/components/schemas/HrefObject"
                }
              ]
            }
          }
        },
        {
          "readOnly": true
        }
      ]
    }
  }
}

UserBlock

{
  "description": "Describes how the account is blocked from access. If `appliesTo` is `ANY_DEVICES`, then the account is blocked for all devices. If `appliesTo` is `UNKNOWN_DEVICES`, then the account is only blocked for unknown devices.",
  "type": "object",
  "properties": {
    "appliesTo": {
      "type": "string",
      "readOnly": true,
      "description": "The devices that the block applies to",
      "enum": [
        "ANY_DEVICES",
        "UNKNOWN_DEVICES"
      ],
      "x-enumDescriptions": {
        "ANY_DEVICES": "The account is blocked for all devices",
        "UNKNOWN_DEVICES": "The account is only blocked for unknown devices"
      }
    },
    "type": {
      "type": "string",
      "readOnly": true,
      "description": "Type of access block",
      "enum": [
        "DEVICE_BASED"
      ]
    }
  }
}

UserCredentials

{
  "description": "Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the org.",
  "type": "object",
  "properties": {
    "password": {
      "$ref": "#/components/schemas/PasswordCredential"
    },
    "provider": {
      "$ref": "#/components/schemas/AuthenticationProvider"
    },
    "recovery_question": {
      "$ref": "#/components/schemas/RecoveryQuestionCredential"
    }
  }
}

UserGetSingleton

{
  "allOf": [
    {
      "$ref": "#/components/schemas/User"
    },
    {
      "type": "object",
      "properties": {
        "_embedded": {
          "type": "object",
          "description": "The embedded resources related to the object if the `expand` query parameter is specified",
          "properties": {
            "blocks": {
              "type": "array",
              "description": "A list of access block details for the user account",
              "items": {
                "$ref": "#/components/schemas/UserBlock"
              }
            }
          }
        }
      }
    }
  ]
}

UserProfile

{
  "additionalProperties": true,
  "description": "Specifies the default and custom profile properties for a user.\n\nThe default user profile is based on the [System for Cross-domain Identity Management: Core Schema](https://datatracker.ietf.org/doc/html/rfc7643).\n\nThe only permitted customizations of the default profile are to update permissions, change whether the `firstName` and `lastName` properties are nullable, and specify a [pattern](https://developer.okta.com/docs/reference/api/schemas/#login-pattern-validation) for `login`. You can use the Profile Editor in the Admin Console or the [Schemas API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UISchema/#tag/UISchema) to make schema modifications.\n\nYou can extend user profiles with custom properties. You must first add the custom property to the user profile schema before you reference it.\nYou can use the Profile Editor in the Admin Console or the [Schemas API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UISchema/#tag/UISchema) to manage schema extensions.\n\nCustom attributes can contain HTML tags. It's the client's responsibility to escape or encode this data before displaying it. Use [best-practices](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) to prevent cross-site scripting.",
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The city or locality of the user's address (`locality`)",
      "maxLength": 128,
      "nullable": true
    },
    "costCenter": {
      "type": "string",
      "description": "Name of the cost center assigned to a user",
      "nullable": true
    },
    "countryCode": {
      "description": "The country name component of the user's address (`country`). For validation, see [ISO 3166-1 alpha 2 \"short\" code format](https://datatracker.ietf.org/doc/html/draft-ietf-scim-core-schema-22#ref-ISO3166).",
      "type": "string",
      "maxLength": 2,
      "nullable": true
    },
    "department": {
      "type": "string",
      "description": "Name of the user's department"
    },
    "displayName": {
      "type": "string",
      "description": "Name of the user suitable for display to end users",
      "nullable": true
    },
    "division": {
      "type": "string",
      "description": "Name of the user's division",
      "nullable": true
    },
    "email": {
      "type": "string",
      "description": "The primary email address of the user. For validation, see [RFC 5322 Section 3.2.3](https://datatracker.ietf.org/doc/html/rfc5322#section-3.2.3).",
      "format": "email",
      "minLength": 5,
      "maxLength": 100
    },
    "employeeNumber": {
      "description": "The organization or company assigned unique identifier for the user",
      "type": "string"
    },
    "firstName": {
      "type": "string",
      "description": "Given name of the user (`givenName`)",
      "minLength": 1,
      "maxLength": 50,
      "nullable": true
    },
    "honorificPrefix": {
      "type": "string",
      "description": "Honorific prefix(es) of the user, or title in most Western languages",
      "nullable": true
    },
    "honorificSuffix": {
      "type": "string",
      "description": "Honorific suffix(es) of the user",
      "nullable": true
    },
    "lastName": {
      "type": "string",
      "description": "The family name of the user (`familyName`)",
      "minLength": 1,
      "maxLength": 50,
      "nullable": true
    },
    "locale": {
      "type": "string",
      "description": "The user's default location for purposes of localizing items such as currency, date time format, numerical representations, and so on.\nA locale value is a concatenation of the ISO 639-1 two-letter language code, an underscore, and the ISO 3166-1 two-letter country code. For example, en_US specifies the language English and country US. This value is `en_US` by default."
    },
    "login": {
      "type": "string",
      "description": "The unique identifier for the user (`username`). For validation, see [Login pattern validation](https://developer.okta.com/docs/reference/api/schemas/#login-pattern-validation).\n\nEvery user within your Okta org must have a unique identifier for a login. This constraint applies to all users you import from other systems or applications such as Active Directory. Your organization is the top-level namespace to mix and match logins from all your connected applications or directories. Careful consideration of naming conventions for your login identifier will make it easier to onboard new applications in the future.\n\nLogins are not considered unique if they differ only in case and/or diacritical marks. If one of your users has a login of `Isaac.Brock@example.com`, there cannot be another user whose login is `isaac.brock@example.com`, nor `isáàc.bröck@example.com`.\n\nOkta has a default ambiguous name resolution policy for usernames that include @-signs. By default, usernames must be formatted as email addresses and thus always include @-signs. You can remove that restriction using either the Admin Console or the [Schemas API](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Schema/). Users can sign in with their non-qualified short name (for example: `isaac.brock` with username `isaac.brock@example.com`) as long as the short name is still unique within the org.",
      "maxLength": 100,
      "minLength": 5
    },
    "manager": {
      "type": "string",
      "description": "The `displayName` of the user's manager",
      "nullable": true
    },
    "managerId": {
      "type": "string",
      "description": "The `id` of the user's manager",
      "nullable": true
    },
    "middleName": {
      "type": "string",
      "description": "The middle name of the user",
      "nullable": true
    },
    "mobilePhone": {
      "type": "string",
      "description": "The mobile phone number of the user",
      "maxLength": 100,
      "minLength": 0,
      "nullable": true
    },
    "nickName": {
      "type": "string",
      "description": "The casual way to address the user in real life",
      "nullable": true
    },
    "organization": {
      "type": "string",
      "description": "Name of the the user's organization",
      "nullable": true
    },
    "postalAddress": {
      "type": "string",
      "description": "Mailing address component of the user's address",
      "maxLength": 4096,
      "nullable": true
    },
    "preferredLanguage": {
      "type": "string",
      "description": "The user's preferred written or spoken language. For validation, see [RFC 7231 Section 5.3.5](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.5).",
      "nullable": true
    },
    "primaryPhone": {
      "type": "string",
      "description": "The primary phone number of the user such as a home number",
      "maxLength": 100,
      "minLength": 0,
      "nullable": true
    },
    "profileUrl": {
      "type": "string",
      "description": "The URL of the user's online profile. For example, a web page. See [URL](https://datatracker.ietf.org/doc/html/rfc1808).",
      "nullable": true
    },
    "secondEmail": {
      "type": "string",
      "format": "email",
      "description": "The secondary email address of the user typically used for account recovery. For validation, see [RFC 5322 Section 3.2.3](https://datatracker.ietf.org/doc/html/rfc5322#section-3.2.3).",
      "maxLength": 100,
      "nullable": true
    },
    "state": {
      "type": "string",
      "description": "The state or region component of the user's address (`region`)",
      "maxLength": 128,
      "nullable": true
    },
    "streetAddress": {
      "type": "string",
      "description": "The full street address component of the user's address",
      "maxLength": 1024,
      "nullable": true
    },
    "timezone": {
      "type": "string",
      "description": "The user's time zone",
      "nullable": true
    },
    "title": {
      "type": "string",
      "description": "The user's title, such as Vice President",
      "nullable": true
    },
    "userType": {
      "type": "string",
      "description": "The property used to describe the organization-to-user relationship, such as employee or contractor\n\n> **Note:** The `userType` property is a standard string attribute and should be treated as a descriptive label rather than a functional setting. Unlike a user's assigned user [`type`](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/createUser!path=type&t=request), this property is purely informational and doesn't influence the behavior of the Okta platform.",
      "nullable": true
    },
    "zipCode": {
      "type": "string",
      "description": "The ZIP code or postal code component of the user's address (`postalCode`)",
      "maxLength": 50,
      "nullable": true
    }
  }
}

UserStatus

{
  "description": "The current status of the user.\n\nThe status of a user changes in response to explicit events, such as admin-driven lifecycle changes, user login, or self-service password recovery. Okta doesn't asynchronously sweep through users and update their password expiry state, for example. Instead, Okta evaluates password policy at login time, notices the password has expired, and moves the user to the expired state. When running reports, remember that the data is valid as of the last login or lifecycle event for that user.\n\n> **Note:** The `ACTIVATING` status is a transitional status that occurs when a user is being activated but hasn't completed the activation process. This status isn't directly settable through the API, nor should you use it for any of your user management workflows.",
  "type": "string",
  "enum": [
    "ACTIVE",
    "DEPROVISIONED",
    "LOCKED_OUT",
    "PASSWORD_EXPIRED",
    "PROVISIONED",
    "RECOVERY",
    "STAGED",
    "SUSPENDED"
  ],
  "readOnly": true
}

securitySchemes

apiToken

{
  "description": "Pass the API token as the Authorization header value prefixed with SSWS: `Authorization: SSWS {API Token}`",
  "name": "Authorization",
  "type": "apiKey",
  "in": "header"
}

oauth2

{
  "type": "oauth2",
  "description": "Pass the access_token as the value of the Authorization header: `Authorization: Bearer {access_token}`",
  "flows": {
    "authorizationCode": {
      "authorizationUrl": "/oauth2/v1/authorize",
      "tokenUrl": "/oauth2/v1/token",
      "scopes": {
        "okta.agentPools.manage": "Allows the app to create and manage agent pools in your Okta organization",
        "okta.agentPools.read": "Allows the app to read agent pools in your Okta organization",
        "okta.apiTokens.manage": "Allows the app to manage API Tokens in your Okta organization",
        "okta.apiTokens.read": "Allows the app to read API Tokens in your Okta organization",
        "okta.appGrants.manage": "Allows the app to create and manage grants in your Okta organization",
        "okta.appGrants.read": "Allows the app to read grants in your Okta organization",
        "okta.apps.interclientTrust.manage": "Allows the app to manage trusted relationship for native to web SSO",
        "okta.apps.interclientTrust.read": "Allows the app to read configured trusted relationship for native to web SSO",
        "okta.apps.manage": "Allows the app to create and manage Apps in your Okta organization",
        "okta.apps.read": "Allows the app to read information about Apps in your Okta organization",
        "okta.authenticators.manage": "Allows the app to manage all authenticators. For example, enrollments or resets.",
        "okta.authenticators.read": "Allows the app to read org authenticators information",
        "okta.authorizationServers.manage": "Allows the app to create and manage Authorization Servers in your Okta organization",
        "okta.authorizationServers.read": "Allows the app to read information about Authorization Servers in your Okta organization",
        "okta.behaviors.manage": "Allows the app to create and manage behavior detection rules in your Okta organization",
        "okta.behaviors.read": "Allows the app to read behavior detection rules in your Okta org",
        "okta.botProtection.manage": "Allows the app to manage bot protection configuration in your Okta org",
        "okta.botProtection.read": "Allows the app to read bot protection configuration in your Okta org",
        "okta.brands.manage": "Allows the app to create and manage Brands and Themes in your Okta organization",
        "okta.brands.read": "Allows the app to read information about Brands and Themes in your Okta organization",
        "okta.captchas.manage": "Allows the app to create and manage CAPTCHAs in your Okta organization",
        "okta.captchas.read": "Allows the app to read information about CAPTCHAs in your Okta organization",
        "okta.customTelephonyProvider.manage": "Allows the app to create and manage custom telephony provider credentials",
        "okta.customTelephonyProvider.read": "Allows the app to read custom telephony provider credentials",
        "okta.deviceAssurance.manage": "Allows the app to manage device assurances",
        "okta.deviceAssurance.read": "Allows the app to read device assurances",
        "okta.deviceIntegrations.manage": "Allows the app to manage device integrations",
        "okta.deviceIntegrations.read": "Allows the app to read device integrations",
        "okta.devicePostureChecks.manage": "Allows the app to manage device posture checks",
        "okta.devicePostureChecks.read": "Allows the app to read device posture checks",
        "okta.devices.manage": "Allows the app to manage device status transitions and delete a device",
        "okta.devices.read": "Allows the app to read the existing device's profile and search devices",
        "okta.directories.groups.manage": "Allows the app to manage AD/LDAP groups for your Okta organization",
        "okta.directories.groups.read": "Allows the app to read AD/LDAP groups for your Okta organization",
        "okta.domains.manage": "Allows the app to manage custom Domains for your Okta organization",
        "okta.domains.read": "Allows the app to read information about custom Domains for your Okta organization",
        "okta.dr.manage": "Allows the app to manage disaster recovery",
        "okta.dr.read": "Allows the app to read the disaster recovery status",
        "okta.emailDomains.manage": "Allows the app to manage Email Domains for your Okta organization",
        "okta.emailDomains.read": "Allows the app to read information about Email Domains for your Okta organization",
        "okta.emailServers.manage": "Allows the app to manage Email Servers for your Okta organization",
        "okta.emailServers.read": "Allows the app to read information about Email Servers for your Okta organization",
        "okta.eventHooks.manage": "Allows the app to create and manage Event Hooks in your Okta organization",
        "okta.eventHooks.read": "Allows the app to read information about Event Hooks in your Okta organization",
        "okta.features.manage": "Allows the app to create and manage Features in your Okta organization",
        "okta.features.read": "Allows the app to read information about Features in your Okta organization",
        "okta.groups.manage": "Allows the app to create and manage groups in your Okta organization",
        "okta.groups.read": "Allows the app to read information about groups and their members in your Okta organization",
        "okta.identitySources.manage": "Allows the custom identity sources to manage user entities in your Okta organization",
        "okta.identitySources.read": "Allows to read session information for custom identity sources in your Okta organization",
        "okta.idps.manage": "Allows the app to create and manage Identity Providers in your Okta organization",
        "okta.idps.read": "Allows the app to read information about Identity Providers in your Okta organization",
        "okta.inlineHooks.manage": "Allows the app to create and manage Inline Hooks in your Okta organization",
        "okta.inlineHooks.read": "Allows the app to read information about Inline Hooks in your Okta organization",
        "okta.linkedObjects.manage": "Allows the app to manage linked object definitions in your Okta organization",
        "okta.linkedObjects.read": "Allows the app to read linked object definitions in your Okta organization",
        "okta.logStreams.manage": "Allows the app to create and manage log streams in your Okta organization",
        "okta.logStreams.read": "Allows the app to read information about log streams in your Okta organization",
        "okta.logs.read": "Allows the app to read information about System Log entries in your Okta organization",
        "okta.networkZones.manage": "Allows the app to create and manage Network Zones in your Okta organization",
        "okta.networkZones.read": "Allows the app to read Network Zones in your Okta organization",
        "okta.oauthIntegrations.manage": "Allows the app to create and manage API service Integration instances in your Okta organization",
        "okta.oauthIntegrations.read": "Allows the app to read API service Integration instances in your Okta organization",
        "okta.orgs.manage": "Allows the app to manage organization-specific details for your Okta organization",
        "okta.orgs.read": "Allows the app to read organization-specific details about your Okta organization",
        "okta.policies.manage": "Allows the app to manage policies in your Okta organization",
        "okta.policies.read": "Allows the app to read information about policies in your Okta organization",
        "okta.principalRateLimits.manage": "Allows the app to create and manage Principal Rate Limits in your Okta organization",
        "okta.principalRateLimits.read": "Allows the app to read information about Principal Rate Limits in your Okta organization",
        "okta.profileMappings.manage": "Allows the app to manage user profile mappings in your Okta organization",
        "okta.profileMappings.read": "Allows the app to read user profile mappings in your Okta organization",
        "okta.pushProviders.manage": "Allows the app to create and manage push notification providers such as APNs and FCM",
        "okta.pushProviders.read": "Allows the app to read push notification providers such as APNs and FCM",
        "okta.rateLimits.manage": "Allows the app to create and manage rate limits in your Okta organization",
        "okta.rateLimits.read": "Allows the app to read information about rate limits in your Okta organization",
        "okta.realmAssignments.manage": "Allows a user to manage realm assignments",
        "okta.realmAssignments.read": "Allows a user to read realm assignments",
        "okta.realms.manage": "Allows the app to create new realms and to manage their details",
        "okta.realms.read": "Allows the app to read the existing realms and their details",
        "okta.roles.manage": "Allows the app to manage administrative role assignments for users in your Okta organization. Delegated admins with this permission can only manage user credential fields and not the credential values themselves.",
        "okta.roles.read": "Allows the app to read administrative role assignments for users in your Okta organization. Delegated admins with this permission can only read user credential fields and not the credential values themselves.",
        "okta.schemas.manage": "Allows the app to create and manage Schemas in your Okta organization",
        "okta.schemas.read": "Allows the app to read information about Schemas in your Okta organization",
        "okta.securityEventsProviders.manage": "Allows the app to create and manage Security Events Providers in your Okta organization",
        "okta.securityEventsProviders.read": "Allows the app to read information about Security Events Providers in your Okta organization",
        "okta.serviceAccounts.manage": "Allows the app to manage service accounts in your Okta organization",
        "okta.serviceAccounts.okta.manage": "Allows the app to manage Okta managed user accounts in your Okta org",
        "okta.serviceAccounts.okta.read": "Allows the app to read Okta managed user accounts in your Okta org",
        "okta.serviceAccounts.read": "Allows the app to read service accounts in your Okta organization",
        "okta.sessions.manage": "Allows the app to manage all sessions in your Okta organization",
        "okta.sessions.read": "Allows the app to read all sessions in your Okta organization",
        "okta.templates.manage": "Allows the app to manage all custom templates in your Okta organization",
        "okta.templates.read": "Allows the app to read all custom templates in your Okta organization",
        "okta.threatInsights.manage": "Allows the app to manage all ThreatInsight configurations in your Okta organization",
        "okta.threatInsights.read": "Allows the app to read all ThreatInsight configurations in your Okta organization",
        "okta.trustedOrigins.manage": "Allows the app to manage all Trusted Origins in your Okta organization",
        "okta.trustedOrigins.read": "Allows the app to read all Trusted Origins in your Okta organization",
        "okta.uischemas.manage": "Allows the app to manage all the UI Schemas in your Okta organization",
        "okta.uischemas.read": "Allows the app to read all the UI Schemas in your Okta organization",
        "okta.userRisk.manage": "Allows the app to manage a user's risk in your Okta org",
        "okta.userRisk.read": "Allows the app to read a user's risk in your Okta org",
        "okta.userTypes.manage": "Allows the app to manage user types in your Okta org",
        "okta.userTypes.read": "Allows the app to read user types in your Okta org",
        "okta.users.manage": "Allows the app to create new users and to manage all users' profile and credentials information",
        "okta.users.read": "Allows the app to read the existing users' profiles and credentials",
        "ssf.manage": "Allows the app to create and manage Shared Signals Framework (SSF) in your Okta organization",
        "ssf.read": "Allows the app to read information about Shared Signals Framework (SSF) in your Okta organization"
      }
    }
  }
}

Path metadata and references

{
  "/api/v1/users/{id}": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathId"
      }
    ]
  },
  "/api/v1/users/{id}/lifecycle/unlock": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathId"
      }
    ]
  },
  "/api/v1/users/{id}/lifecycle/expire_password": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathId"
      }
    ]
  },
  "/api/v1/users/{userId}/credentials/forgot_password": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathUserId"
      }
    ]
  },
  "/api/v1/users/{id}/groups": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathId"
      }
    ]
  },
  "/api/v1/groups/{groupId}/users/{userId}": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathGroupId"
      },
      {
        "$ref": "#/components/parameters/pathUserId"
      }
    ]
  },
  "/api/v1/groups/{groupId}/users": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathGroupId"
      }
    ]
  },
  "/api/v1/users/{id}/lifecycle/forgot_password": {
    "parameters": [
      {
        "$ref": "#/components/parameters/pathId"
      }
    ]
  }
}

Document metadata and extensions

{
  "openapi": "3.0.3",
  "info": {
    "title": "Okta Admin Management API",
    "description": "Allows customers to easily access the Okta Management APIs",
    "termsOfService": "https://developer.okta.com/terms/",
    "contact": {
      "name": "Okta Developer Team",
      "url": "https://developer.okta.com/",
      "email": "devex-public@okta.com"
    },
    "license": {
      "name": "Apache-2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "2026.44.0",
    "x-logo": {
      "url": "logo.svg",
      "backgroundColor": "transparent",
      "altText": "Okta Developer"
    }
  },
  "tags": [
    {
      "name": "Group",
      "x-displayName": "Groups",
      "description": "The Groups API provides operations to manage Okta groups and their user members in your org."
    },
    {
      "name": "User",
      "x-displayName": "Users",
      "description": "The Users API provides operations to manage users in your org.\n> **Note:** Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs.\n> OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See [Okta API authentication methods](https://developer.okta.com/docs/api/openapi/okta-oauth/guides/overview/).\n\n### User status\nThe following diagram shows the flow of user status:\n\n<img alt=\"Example\" src=\"https://developer.okta.com/docs/api/images/users/okta-user-status.png\" width=\"1000\"/>\n\n### User creation scenarios\n\n The following table describes the user experience and expectation of user status and welcome screen, depending on which options (security question and answer, password, and activate query) are defined during user creation.\n\n  **User creation details and outcomes**\n\n  | Security Q & A   | Password   | Activate Query Parameter   | User Status                | Login Credential                | Welcome Screen   |\n  |     -----        |  --------  |  ------------------------  |  -------------             |  ----------------------         |  --------------  |\n  |                  |            | FALSE                      | `STAGED`                   |                                 |                  |\n  |                  |            | TRUE                       | `PROVISIONED` or `ACTIVE`  | One-Time Token (Email) or Email | X                |\n  | X                |            | FALSE                      | `STAGED`                   |                                 |                  |\n  | X                |            | TRUE                       | `PROVISIONED` or `ACTIVE`  | One-Time Token (Email) or Email | X                |\n  |                  | X          | FALSE                      | `STAGED`                   |                                 |                  |\n  |                  | X          | TRUE                       | `ACTIVE`                   | Password                        | X                |\n  | X                | X          | FALSE                      | `STAGED`                   |                                 |                  |\n  | X                | X          | TRUE                       | `ACTIVE`                   | Password                        |                  |\n\nCreating users with a `FEDERATION` or `SOCIAL` provider sets the user status to either `ACTIVE` or `STAGED` based on the `activate` query parameter since these two providers don't support a `password` or `recovery_question` credential.\n\nMore information about the use cases are in the following sections and in the examples for [Create a user](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/#tag/User/operation/createUser).\n\n#### Create user with optional password\n\nWhen making the password optional, the user status following user creation can be affected by the enrollment policy. See [Create an authenticator enrollment policy](https://help.okta.com/okta_help.htm?type=oie&id=ext-create-mfa-policy).\n\nBased on the group memberships that are specified when the user is created, a password may or may not be required to make the user's status `ACTIVE`. The groups assigned to the user determines the enrollment policy applied to the user. If the enrollment policy has the password authenticator set to `required`, then the user's status is determined by if the user is created with a password:\n\n* Created with a password - the user status is set to `PROVISIONED` and a One-Time Token is sent to the user through email\n* Created without a password - the user status is set to `ACTIVE` and they can immediately sign in using their password authenticator\n\nIf the user doesn't have an enrolled authenticator, Okta sets the user to `PROVISIONED` and sends an activation link. The user must click the activation link before they can sign in. The activation link provides a baseline assurance that can be used to enroll in other authenticators. If the user has one or more enrolled authenticators at activation time, they're set to `ACTIVE` and can sign in directly.\n\nSee [Passwordless authentication](https://help.okta.com/okta_help.htm?type=oie&id=ext-passwordless-auth) in the help documentation.\n\n#### Create user without credentials\n\nCreates a user without a `password` or a recovery `question` and `answer`.\n\nIf appropriate, when the user is activated, an email is sent to the user with an activation token that the user can use to complete the activation process.\n\nThis is the default flow for new user registration using the Admin Console.\n\n#### Create user with recovery question\n\nCreates a user without a `password`.\n\nWhen the user is activated, an email is sent to the user with an activation token that can be used to complete the activation process.\nThis flow is useful if migrating users from an existing user store.\n\n#### Create user with password\n\nCreates a user without a recovery `question` and `answer`.\n\nThe new user is able to sign in after activation with the assigned password. This flow is common when developing a custom user registration experience.\n> **Important:** Don't generate or send a one-time activation token when activating users with an assigned password. Users should sign in with their assigned password.\n\n> **Note:** You can also use this scenario to create a user without sending an activation email. See this [Knowledge Base article](https://support.okta.com/help/s/article/How-to-Avoid-Sending-a-Welcome-Email?language=en_US#:~:text=For%20users%20imported%20from%20the,t%20send%20new%20user%20activation).\n\n#### Create user with imported hashed password\n\nCreates a user with a specified hashed password.\n\nThe new user is able to sign in after activation with the specified password.\n\nThis flow is common when migrating users from another data store in cases where we want to allow the users to retain their current passwords.\n> **Important:** Do not generate or send a one-time activation token when activating users with an imported password. Users should login with their imported password.\n\n#### Create user with password import inline hook\n\nCreates a user with a `Password Hook` object specifying that a password inline hook should be used to handle password verification.\n\nThe password inline hook is triggered to handle verification of the end user's password the first time the user tries to sign in, with Okta calling the password inline hook to check that the password the user supplied is valid. If the password is valid, Okta stores the hash of the password that was provided and can authenticate the user independently from then on. See [Create a password import inline hook](https://developer.okta.com/docs/api/openapi/okta-management/management/tags/inlinehook/#tag/InlineHook/operation/createPasswordImportInlineHook) for more details.\n\nThe new user is able to sign in after activation with the valid password. This flow supports migrating users from another data store in cases where we wish to allow the users to retain their current passwords.\n> **Important:** Don't generate or send a one-time activation token when activating users with an password inline hook. Users should sign in with their existing password to be imported using the password import inline hook.\n\n#### Create user with password and recovery question\n\nCreates a new user with a password and recovery `question` and `answer`.\n\nThe new user is able to log in with the assigned password after activation. This flow is common when developing a custom user-registration experience.\n> **Important:** Don't generate or send a one-time activation token when activating users with an assigned password. Users should login with their assigned password.\n\n#### Create user with authentication provider\n\nCreates a new passwordless user with a `SOCIAL` or `FEDERATION` authentication provider that must be authenticated through a trusted identity provider.\n\n#### Create user in group\n\nCreates a user that is added to the specified groups upon creation.\n\nUse this in conjunction with other create operations for a group admin that's scoped to create users only in specified groups. The request can specify up to 20 group IDs. (This limit applies only when creating a user. You can add the user later to more groups.)\n\n#### Create user with non-default user type\n\nCreates a user with a specified user type. You can include the type specification with any of the above Create user operations. This example demonstrates creating a user without credentials.\nThe user type determines which [Schema](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Schema/) applies to that user. After you create a user, you can assign the user a different user type using the full replacement [PUT operation](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserType/#tag/UserType/operation/replaceUserType).\n\n### Links object\n\nThe links object specifies link relations. See [`_links`](https://developer.okta.com/docs/api/openapi/okta-management/management/user/listusers!c=200&path=_links&t=response).\n\n> **Note:** This links object is different from [linked objects](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/LinkedObject/).\n\n#### Individual users versus collection of users\n\nFor an individual user result, the links object contains a full set of link relations available for that user as determined by your policies. For a collection of users, the links object contains only the `self` link. Operations that return a collection of users include [List all users](https://developer.okta.com/docs/api/openapi/okta-management/management/user/listusers) and [List all member users](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/#tag/Group/operation/listGroupUsers).\n\nThe following table shows some links that may be available on a user, as determined by your policies:\n\n|   Link Relation Type   |                                                  Description                                                                                                                        |\n|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n|self\t                   |  A self-referential link to this user                                                                                                                                               |\n|activate\t               |  Lifecycle action to [activate the user](https://developer.okta.com/docs/api/openapi/okta-management/management/userlifecycle/activateuser)                                           |\n|deactivate              |\tLifecycle action to [deactivate the user](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/deactivateUser)                                       |\n|suspend                 |\tLifecycle action to [suspend the user](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/suspendUser)                                             |\n|unsuspend               |\tLifecycle action to [unsuspend the user](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/unsuspendUser)                                         |\n|resetPassword           |\tLifecycle action to [trigger a password reset](https://developer.okta.com/docs/api/openapi/okta-management/management/usercred/resetpassword)                                             |\n|expirePassword          |\tLifecycle action to [expire the user's password](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserCred/#tag/UserCred/operation/expirePassword)                                          |\n|resetFactors            |\tLifecycle action to [reset all MFA factors](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/resetFactors)                                       |\n|unlock                  |\tLifecycle action to [unlock a locked-out user](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/unlockUser)                                      |\n|forgotPassword          |\t[Resets a user's password](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserCred/#tag/UserCred/operation/forgotPassword) by validating the user's recovery credential.                  |\n|changePassword          |\t[Changes a user's password](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserCred/#tag/UserCred/operation/changePassword) validating the user's current password                        |\n|changeRecoveryQuestion  |\t[Changes a user's recovery credential](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserCred/#tag/UserCred/operation/changeRecoveryQuestion) by validating the user's current password  |"
    },
    {
      "name": "UserCred",
      "x-displayName": "User Credentials",
      "description": "The User Credentials API provides operations to manage user credentials in your org."
    },
    {
      "name": "UserLifecycle",
      "x-displayName": "User Lifecycle",
      "description": "The User Lifecycle API provides lifecycle operations, which are non-idempotent operations that initiate a state transition for a user's status. Some operations are asynchronous while others are synchronous.\nThe user's current status limits what operations are allowed."
    },
    {
      "name": "UserResources",
      "x-displayName": "User Resources",
      "description": "The User Resources API provides operations related to user resources."
    }
  ]
}
Interactive API explorer (requires JavaScript)