Users

The User API provides operations to manage users in your organization.

List all Users
OAuth 2.0: okta.users.read

Lists all users that do not have a status of 'DEPROVISIONED' (by default), up to the maximum (200 for most orgs), with pagination. A subset of users can be returned that match a supported filter expression or search criteria.

Request
query Parameters
q
string

Finds a user that matches firstName, lastName, and email properties

after
string

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.

limit
integer <int32>
Default: 200

Specifies the number of results returned. Defaults to 10 if q is provided.

filter
string

Filters users with a supported expression for a subset of properties

search
string

Searches for users with a supported filtering expression for most properties. Okta recommends using this parameter for search for best performance.

sortBy
string
sortOrder
string

Sorting is done in ASCII sort order (that is, by ASCII character value), but isn't case sensitive.

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/users
Request samples
Response samples
application/json
[
  • {
    • "id": "00u118oQYT4TBGuay0g4",
    • "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": {
      },
    • "profile": {
      },
    • "realmId": "guo1afiNtSnZYILxO0g4",
    • "credentials": {
      },
    }
]

Create a User
OAuth 2.0: okta.users.manage

Creates a new user in your Okta organization with or without credentials

Legal Disclaimer
After a user is added to the Okta directory, they receive an activation email. As part of signing up for this service, you agreed not to use Okta's service/product to spam and/or send unsolicited messages. Please refrain from adding unrelated accounts to the directory as Okta is not responsible for, and disclaims any and all liability associated with, the activation email's content. You, and you alone, bear responsibility for the emails sent to any recipients.

Request
query Parameters
activate
boolean
Default: true

Executes activation lifecycle operation when creating the user

provider
boolean
Default: false

Indicates whether to create a user with a specified authentication provider

nextLogin
string (UserNextLogin)

With activate=true, set nextLogin to "changePassword" to have the password be EXPIRED, so user must change it the next time they log in.

Value: "changePassword"
Request Body schema: application/json
required
object (UserCredentials)
object (PasswordCredential)

When a user has a valid password, imported hashed password, or password hook, and a response object contains a 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).

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a Password object when creating or updating a user, but not for other operations. See Create User with Imported Hashed Password for information on using this object when creating a user. When updating a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user logs in. This allows an existing password to be imported into Okta directly from some other store. See Create User with Password Hook for information on using this object when creating a user.

value
string <password>

Specifies the password for a user. The Password Policy validates this password.

object (AuthenticationProvider)

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 organization. The provider object is read-only.

object (RecoveryQuestionCredential)

Specifies a secret question and answer that's validated (case insensitive) when a user forgets their password or unlocks their account. The answer property is write-only.

answer
string [ 1 .. 100 ]

The recovery question answer

question
string [ 1 .. 100 ]

The recovery question

groupIds
Array of strings
required
object (UserProfile)

Specifies the default and custom profile properties for a user.

The default user profile is based on the System for Cross-domain Identity Management: Core Schema. The only permitted customizations of the default profile are to update permissions, change whether the firstName and lastName properties are nullable, and specify a pattern for login. You can use the Profile Editor in the administrator UI or the Schemas API to make schema modifications.

You can extend user profiles with custom properties. You must first add the custom property to the user profile schema before you reference it. You can use the Profile Editor in the Admin console or the Schemas API to manage schema extensions.

Custom attributes may contain HTML tags. It's the client's responsibility to escape or encode this data before displaying it. Use best-practices to prevent cross-site scripting.

city
string or null <= 128 characters

The city or locality of the user's address (locality)

costCenter
string or null

Name of the cost center assigned to a user

countryCode
string or null <= 2 characters

The country name component of the user's address (country)

department
string

Name of the user's department

displayName
string or null

Name of the user suitable for display to end users

division
string or null

Name of the user's division

email
string <email> [ 5 .. 100 ] characters

The primary email address of the user. For validation, see RFC 5322 Section 3.2.3.

employeeNumber
string

The organization or company assigned unique identifier for the user

firstName
string or null [ 1 .. 50 ] characters

Given name of the user (givenName)

honorificPrefix
string or null

Honorific prefix(es) of the user, or title in most Western languages

honorificSuffix
string or null

Honorific suffix(es) of the user

lastName
string or null [ 1 .. 50 ] characters

The family name of the user (familyName)

locale
string

The user's default location for purposes of localizing items such as currency, date time format, numerical representations, and so on. A 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
string [ 5 .. 100 ] characters

The unique identifier for the user (username). For validation, see Login pattern validation. See also Okta login.

manager
string or null

The displayName of the user's manager

managerId
string or null

The id of the user's manager

middleName
string or null

The middle name of the user

mobilePhone
string or null [ 0 .. 100 ] characters

The mobile phone number of the user

nickName
string or null

The casual way to address the user in real life

organization
string or null

Name of the the user's organization

postalAddress
string or null <= 4096 characters

Mailing address component of the user's address

preferredLanguage
string or null

The user's preferred written or spoken language

primaryPhone
string or null [ 0 .. 100 ] characters

The primary phone number of the user such as a home number

profileUrl
string or null

The URL of the user's online profile. For example, a web page. See URL.

secondEmail
string or null <email> [ 5 .. 100 ] characters

The secondary email address of the user typically used for account recovery

state
string or null <= 128 characters

The state or region component of the user's address (region)

streetAddress
string or null <= 1024 characters

The full street address component of the user's address

timezone
string or null

The user's time zone

title
string or null

The user's title, such as Vice President

userType
string or null

The property used to describe the organization-to-user relationship, such as employee or contractor

zipCode
string or null <= 50 characters

The ZIP code or postal code component of the user's address (postalCode)

property name*
additional property
any
realmId
string
The ID of the realm in which the user is residing
object

The ID of the user type. Add this value if you want to create a user with a non-default user type. The user type determines which schema applies to that user. After a user has been created, the user can only be assigned a different user type by an administrator through a full replacement (PUT) operation.

id
string

The ID of the user type

Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/users
Request samples
application/json
{
  • "credentials": {
    • "password": {
      },
    • "provider": { },
    • "recovery_question": {
      }
    },
  • "groupIds": [
    • "string"
    ],
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "realmId": "guo1bfiNtSnZYILxO0g4",
  • "type": {
    • "id": "string"
    }
}
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "realmId": "guo1bfiNtSnZYILxO0g4",
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "id": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "resetPassword": {
      },
    • "resetFactors": {
      },
    • "expirePassword": {
      },
    • "forgotPassword": {
      },
    • "changeRecoveryQuestion": {
      },
    • "deactivate": {
      },
    • "reactivate": {
      },
    • "changePassword": {
      },
    • "schema": {
      },
    • "suspend": {
      },
    • "unsuspend": {
      },
    • "unlock": {
      },
    • "type": {
      }
    }
}

Retrieve a User
OAuth 2.0: okta.users.read

Retrieves a user from your Okta organization

Request
path Parameters
userId
required
string

ID of an existing Okta user

query Parameters
expand
string

An optional parameter to include metadata in the _embedded attribute. Valid value: blocks

Example: expand=blocks
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}
Request samples
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "realmId": "guo1bfiNtSnZYILxO0g4",
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "id": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { },
    • "blocks": [
      ]
    },
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "resetPassword": {
      },
    • "resetFactors": {
      },
    • "expirePassword": {
      },
    • "forgotPassword": {
      },
    • "changeRecoveryQuestion": {
      },
    • "deactivate": {
      },
    • "reactivate": {
      },
    • "changePassword": {
      },
    • "schema": {
      },
    • "suspend": {
      },
    • "unsuspend": {
      },
    • "unlock": {
      },
    • "type": {
      }
    }
}

Update a User
OAuth 2.0: okta.users.manage

Updates a user partially determined by the request parameters

Request
path Parameters
userId
required
string

ID of an existing Okta user

query Parameters
strict
boolean
Request Body schema: application/json
required
object (UserCredentials)
object (PasswordCredential)

When a user has a valid password, imported hashed password, or password hook, and a response object contains a 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).

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a Password object when creating or updating a user, but not for other operations. See Create User with Imported Hashed Password for information on using this object when creating a user. When updating a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user logs in. This allows an existing password to be imported into Okta directly from some other store. See Create User with Password Hook for information on using this object when creating a user.

value
string <password>

Specifies the password for a user. The Password Policy validates this password.

object (AuthenticationProvider)

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 organization. The provider object is read-only.

object (RecoveryQuestionCredential)

Specifies a secret question and answer that's validated (case insensitive) when a user forgets their password or unlocks their account. The answer property is write-only.

answer
string [ 1 .. 100 ]

The recovery question answer

question
string [ 1 .. 100 ]

The recovery question

object (UserProfile)

Specifies the default and custom profile properties for a user.

The default user profile is based on the System for Cross-domain Identity Management: Core Schema. The only permitted customizations of the default profile are to update permissions, change whether the firstName and lastName properties are nullable, and specify a pattern for login. You can use the Profile Editor in the administrator UI or the Schemas API to make schema modifications.

You can extend user profiles with custom properties. You must first add the custom property to the user profile schema before you reference it. You can use the Profile Editor in the Admin console or the Schemas API to manage schema extensions.

Custom attributes may contain HTML tags. It's the client's responsibility to escape or encode this data before displaying it. Use best-practices to prevent cross-site scripting.

city
string or null <= 128 characters

The city or locality of the user's address (locality)

costCenter
string or null

Name of the cost center assigned to a user

countryCode
string or null <= 2 characters

The country name component of the user's address (country)

department
string

Name of the user's department

displayName
string or null

Name of the user suitable for display to end users

division
string or null

Name of the user's division

email
string <email> [ 5 .. 100 ] characters

The primary email address of the user. For validation, see RFC 5322 Section 3.2.3.

employeeNumber
string

The organization or company assigned unique identifier for the user

firstName
string or null [ 1 .. 50 ] characters

Given name of the user (givenName)

honorificPrefix
string or null

Honorific prefix(es) of the user, or title in most Western languages

honorificSuffix
string or null

Honorific suffix(es) of the user

lastName
string or null [ 1 .. 50 ] characters

The family name of the user (familyName)

locale
string

The user's default location for purposes of localizing items such as currency, date time format, numerical representations, and so on. A 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
string [ 5 .. 100 ] characters

The unique identifier for the user (username). For validation, see Login pattern validation. See also Okta login.

manager
string or null

The displayName of the user's manager

managerId
string or null

The id of the user's manager

middleName
string or null

The middle name of the user

mobilePhone
string or null [ 0 .. 100 ] characters

The mobile phone number of the user

nickName
string or null

The casual way to address the user in real life

organization
string or null

Name of the the user's organization

postalAddress
string or null <= 4096 characters

Mailing address component of the user's address

preferredLanguage
string or null

The user's preferred written or spoken language

primaryPhone
string or null [ 0 .. 100 ] characters

The primary phone number of the user such as a home number

profileUrl
string or null

The URL of the user's online profile. For example, a web page. See URL.

secondEmail
string or null <email> [ 5 .. 100 ] characters

The secondary email address of the user typically used for account recovery

state
string or null <= 128 characters

The state or region component of the user's address (region)

streetAddress
string or null <= 1024 characters

The full street address component of the user's address

timezone
string or null

The user's time zone

title
string or null

The user's title, such as Vice President

userType
string or null

The property used to describe the organization-to-user relationship, such as employee or contractor

zipCode
string or null <= 50 characters

The ZIP code or postal code component of the user's address (postalCode)

property name*
additional property
any
realmId
string
The ID of the realm in which the user is residing
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}
Request samples
application/json
{
  • "credentials": {
    • "password": {
      },
    • "provider": { },
    • "recovery_question": {
      }
    },
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "realmId": "guo1bfiNtSnZYILxO0g4"
}
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "realmId": "guo1bfiNtSnZYILxO0g4",
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "id": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "resetPassword": {
      },
    • "resetFactors": {
      },
    • "expirePassword": {
      },
    • "forgotPassword": {
      },
    • "changeRecoveryQuestion": {
      },
    • "deactivate": {
      },
    • "reactivate": {
      },
    • "changePassword": {
      },
    • "schema": {
      },
    • "suspend": {
      },
    • "unsuspend": {
      },
    • "unlock": {
      },
    • "type": {
      }
    }
}

Replace a User
OAuth 2.0: okta.users.manage

Replaces a user's profile and/or credentials using strict-update semantics

Request
path Parameters
userId
required
string

ID of an existing Okta user

query Parameters
strict
boolean
Request Body schema: application/json
required
object (UserCredentials)
object (PasswordCredential)

When a user has a valid password, imported hashed password, or password hook, and a response object contains a 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).

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a Password object when creating or updating a user, but not for other operations. See Create User with Imported Hashed Password for information on using this object when creating a user. When updating a user with a hashed password, the user must be in the STAGED status.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user logs in. This allows an existing password to be imported into Okta directly from some other store. See Create User with Password Hook for information on using this object when creating a user.

value
string <password>

Specifies the password for a user. The Password Policy validates this password.

object (AuthenticationProvider)

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 organization. The provider object is read-only.

object (RecoveryQuestionCredential)

Specifies a secret question and answer that's validated (case insensitive) when a user forgets their password or unlocks their account. The answer property is write-only.

answer
string [ 1 .. 100 ]

The recovery question answer

question
string [ 1 .. 100 ]

The recovery question

object (UserProfile)

Specifies the default and custom profile properties for a user.

The default user profile is based on the System for Cross-domain Identity Management: Core Schema. The only permitted customizations of the default profile are to update permissions, change whether the firstName and lastName properties are nullable, and specify a pattern for login. You can use the Profile Editor in the administrator UI or the Schemas API to make schema modifications.

You can extend user profiles with custom properties. You must first add the custom property to the user profile schema before you reference it. You can use the Profile Editor in the Admin console or the Schemas API to manage schema extensions.

Custom attributes may contain HTML tags. It's the client's responsibility to escape or encode this data before displaying it. Use best-practices to prevent cross-site scripting.

city
string or null <= 128 characters

The city or locality of the user's address (locality)

costCenter
string or null

Name of the cost center assigned to a user

countryCode
string or null <= 2 characters

The country name component of the user's address (country)

department
string

Name of the user's department

displayName
string or null

Name of the user suitable for display to end users

division
string or null

Name of the user's division

email
string <email> [ 5 .. 100 ] characters

The primary email address of the user. For validation, see RFC 5322 Section 3.2.3.

employeeNumber
string

The organization or company assigned unique identifier for the user

firstName
string or null [ 1 .. 50 ] characters

Given name of the user (givenName)

honorificPrefix
string or null

Honorific prefix(es) of the user, or title in most Western languages

honorificSuffix
string or null

Honorific suffix(es) of the user

lastName
string or null [ 1 .. 50 ] characters

The family name of the user (familyName)

locale
string

The user's default location for purposes of localizing items such as currency, date time format, numerical representations, and so on. A 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
string [ 5 .. 100 ] characters

The unique identifier for the user (username). For validation, see Login pattern validation. See also Okta login.

manager
string or null

The displayName of the user's manager

managerId
string or null

The id of the user's manager

middleName
string or null

The middle name of the user

mobilePhone
string or null [ 0 .. 100 ] characters

The mobile phone number of the user

nickName
string or null

The casual way to address the user in real life

organization
string or null

Name of the the user's organization

postalAddress
string or null <= 4096 characters

Mailing address component of the user's address

preferredLanguage
string or null

The user's preferred written or spoken language

primaryPhone
string or null [ 0 .. 100 ] characters

The primary phone number of the user such as a home number

profileUrl
string or null

The URL of the user's online profile. For example, a web page. See URL.

secondEmail
string or null <email> [ 5 .. 100 ] characters

The secondary email address of the user typically used for account recovery

state
string or null <= 128 characters

The state or region component of the user's address (region)

streetAddress
string or null <= 1024 characters

The full street address component of the user's address

timezone
string or null

The user's time zone

title
string or null

The user's title, such as Vice President

userType
string or null

The property used to describe the organization-to-user relationship, such as employee or contractor

zipCode
string or null <= 50 characters

The ZIP code or postal code component of the user's address (postalCode)

property name*
additional property
any
object

The user type that determines the schema for the user's profile. The type property is a map that identifies the User Type (see User Types). Currently it contains a single element, id. It can be specified when creating a new user, and may be updated by an administrator on a full replace of an existing user (but not a partial update).

id
string

The ID of the user type

Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/users/{userId}
Request samples
application/json
{
  • "credentials": {
    • "password": {
      },
    • "provider": { },
    • "recovery_question": {
      }
    },
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "type": {
    • "id": "string"
    }
}
Response samples
application/json
{
  • "activated": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "credentials": {
    • "password": {
      },
    • "provider": {
      },
    • "recovery_question": {
      }
    },
  • "id": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "passwordChanged": "2019-08-24T14:15:22Z",
  • "profile": {
    • "city": "string",
    • "costCenter": "string",
    • "countryCode": "st",
    • "department": "string",
    • "displayName": "string",
    • "division": "string",
    • "email": "user@example.com",
    • "employeeNumber": "string",
    • "firstName": "string",
    • "honorificPrefix": "string",
    • "honorificSuffix": "string",
    • "lastName": "string",
    • "locale": "string",
    • "login": "string",
    • "manager": "string",
    • "managerId": "string",
    • "middleName": "string",
    • "mobilePhone": "string",
    • "nickName": "string",
    • "organization": "string",
    • "postalAddress": "string",
    • "preferredLanguage": "string",
    • "primaryPhone": "string",
    • "profileUrl": "string",
    • "secondEmail": "user@example.com",
    • "state": "string",
    • "streetAddress": "string",
    • "timezone": "string",
    • "title": "string",
    • "userType": "string",
    • "zipCode": "string"
    },
  • "realmId": "guo1bfiNtSnZYILxO0g4",
  • "status": "ACTIVE",
  • "statusChanged": "2019-08-24T14:15:22Z",
  • "transitioningToStatus": "ACTIVE",
  • "type": {
    • "id": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "resetPassword": {
      },
    • "resetFactors": {
      },
    • "expirePassword": {
      },
    • "forgotPassword": {
      },
    • "changeRecoveryQuestion": {
      },
    • "deactivate": {
      },
    • "reactivate": {
      },
    • "changePassword": {
      },
    • "schema": {
      },
    • "suspend": {
      },
    • "unsuspend": {
      },
    • "unlock": {
      },
    • "type": {
      }
    }
}

Delete a User
OAuth 2.0: okta.users.manage

Deletes a user permanently. This operation can only be performed on users that have a DEPROVISIONED status. This action cannot be recovered!. Calling this on an ACTIVE user will transition the user to DEPROVISIONED.

Request
path Parameters
userId
required
string

ID of an existing Okta user

query Parameters
sendEmail
boolean
Default: false
Responses
204

No Content

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}
Request samples
Response samples
application/json
{
  • "errorCauses": [
    • {
      }
    ],
  • "errorCode": "string",
  • "errorId": "string",
  • "errorLink": "string",
  • "errorSummary": "string"
}

List all User Blocks
OAuth 2.0: okta.users.read

Lists information about how the user is blocked from accessing their account

Request
path Parameters
userId
required
string

ID of an existing Okta user

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/blocks
Request samples
Response samples
application/json
[
  • {
    • "type": "DEVICE_BASED",
    • "appliesTo": "UNKNOWN_DEVICES"
    }
]

List all Clients
OAuth 2.0: okta.users.read

Lists all client resources for which the specified user has grants or tokens

Request
path Parameters
userId
required
string

ID of an existing Okta user

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients
Request samples
Response samples
application/json
[
  • {
    • "client_id": "string",
    • "client_name": "string",
    • "client_uri": "string",
    • "logo_uri": "string",
    • "_links": {
      }
    }
]

List all Grants for a Client
OAuth 2.0: okta.users.read

Lists all grants for a specified user and client

Request
path Parameters
userId
required
string

ID of an existing Okta user

clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
query Parameters
expand
string
after
string
limit
integer <int32>
Default: 20
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients/{clientId}/grants
Request samples
Response samples
application/json
[
  • {
    • "clientId": "string",
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": {
      },
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "scopeId": "okta.users.read",
    • "source": "ADMIN",
    • "status": "ACTIVE",
    • "userId": "string",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Revoke all Grants for a Client
OAuth 2.0: okta.users.manage

Revokes all grants for the specified user and client

Request
path Parameters
userId
required
string

ID of an existing Okta user

clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/clients/{clientId}/grants
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

List all Refresh Tokens for a Client
OAuth 2.0: okta.users.read

Lists all refresh tokens issued for the specified User and Client

Request
path Parameters
userId
required
string

ID of an existing Okta user

clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
query Parameters
expand
string
after
string
limit
integer <int32>
Default: 20
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients/{clientId}/tokens
Request samples
Response samples
application/json
[
  • {
    • "clientId": "string",
    • "created": "2019-08-24T14:15:22Z",
    • "expiresAt": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "issuer": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "scopes": [
      ],
    • "status": "ACTIVE",
    • "userId": "string",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Revoke all Refresh Tokens for a Client
OAuth 2.0: okta.users.manage

Revokes all refresh tokens issued for the specified User and Client

Request
path Parameters
userId
required
string

ID of an existing Okta user

clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/clients/{clientId}/tokens
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Retrieve a Refresh Token for a Client
OAuth 2.0: okta.users.read

Retrieves a refresh token issued for the specified User and Client

Request
path Parameters
userId
required
string

ID of an existing Okta user

clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
tokenId
required
string

id of Token

Example: sHHSth53yJAyNSTQKDJZ
query Parameters
expand
string
limit
integer
Default: 20
after
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/clients/{clientId}/tokens/{tokenId}
Request samples
Response samples
application/json
{
  • "clientId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "issuer": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "scopes": [
    • "string"
    ],
  • "status": "ACTIVE",
  • "userId": "string",
  • "_embedded": {
    • "scopes": [
      ]
    },
  • "_links": {
    • "self": {
      },
    • "app": {
      },
    • "revoke": {
      },
    • "client": {
      },
    • "user": {
      },
    • "authorizationServer": {
      }
    }
}

Revoke a Token for a Client
OAuth 2.0: okta.users.manage

Revokes the specified refresh token

Request
path Parameters
userId
required
string

ID of an existing Okta user

clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
tokenId
required
string

id of Token

Example: sHHSth53yJAyNSTQKDJZ
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/clients/{clientId}/tokens/{tokenId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Change Password
OAuth 2.0: okta.users.manage

Changes a user's password by validating the user's current password. This operation can only be performed on users in STAGED, ACTIVE, PASSWORD_EXPIRED, or RECOVERY status that have a valid password credential

Request
path Parameters
userId
required
string

ID of an existing Okta user

query Parameters
strict
boolean
Request Body schema: application/json
required
object (PasswordCredential)

When a user has a valid password, imported hashed password, or password hook, and a response object contains a 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).

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a Password object when creating or updating a user, but not for other operations. See Create User with Imported Hashed Password for information on using this object when creating a user. When updating a user with a hashed password, the user must be in the STAGED status.

algorithm
string (PasswordCredentialHashAlgorithm)

The algorithm used to generate the hash using the password (and salt, when applicable).

Enum: "BCRYPT" "MD5" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)

Algorithm used to generate the key. Only required for the PBKDF2 algorithm.

Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer

The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.

keySize
integer

Size of the derived key in bytes. Only required for PBKDF2 algorithm.

salt
string

Only required for salted hashes. For BCRYPT, this specifies Radix-64 as the encoded salt used to generate the hash, which must be 22 characters long. For other salted hashes, this specifies the Base64-encoded salt used to generate the hash.

saltOrder
string

Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.

value
string

For SHA-512, SHA-256, SHA-1, MD5, and PBKDF2, this is the actual base64-encoded hash of the password (and salt, if used). This 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 the salt to the password, depending on the saltOrder. If a salt was not used in the source system, then this should just be the 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.

workFactor
integer [ 1 .. 20 ]

Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user logs in. This allows an existing password to be imported into Okta directly from some other store. See Create User with Password Hook for information on using this object when creating a user.

type
string

The type of password inline hook. Currently, must be set to default.

value
string <password>

Specifies the password for a user. The Password Policy validates this password.

object (PasswordCredential)

When a user has a valid password, imported hashed password, or password hook, and a response object contains a 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).

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a Password object when creating or updating a user, but not for other operations. See Create User with Imported Hashed Password for information on using this object when creating a user. When updating a user with a hashed password, the user must be in the STAGED status.

algorithm
string (PasswordCredentialHashAlgorithm)

The algorithm used to generate the hash using the password (and salt, when applicable).

Enum: "BCRYPT" "MD5" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)

Algorithm used to generate the key. Only required for the PBKDF2 algorithm.

Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer

The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.

keySize
integer

Size of the derived key in bytes. Only required for PBKDF2 algorithm.

salt
string

Only required for salted hashes. For BCRYPT, this specifies Radix-64 as the encoded salt used to generate the hash, which must be 22 characters long. For other salted hashes, this specifies the Base64-encoded salt used to generate the hash.

saltOrder
string

Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.

value
string

For SHA-512, SHA-256, SHA-1, MD5, and PBKDF2, this is the actual base64-encoded hash of the password (and salt, if used). This 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 the salt to the password, depending on the saltOrder. If a salt was not used in the source system, then this should just be the 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.

workFactor
integer [ 1 .. 20 ]

Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user logs in. This allows an existing password to be imported into Okta directly from some other store. See Create User with Password Hook for information on using this object when creating a user.

type
string

The type of password inline hook. Currently, must be set to default.

value
string <password>

Specifies the password for a user. The Password Policy validates this password.

revokeSessions
boolean
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/change_password
Request samples
application/json
{
  • "newPassword": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "oldPassword": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "revokeSessions": true
}
Response samples
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      }
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "question": "string"
    }
}

Change Recovery Question
OAuth 2.0: okta.users.manage

Changes a user's recovery question & answer credential by validating the user's current password. This operation can only be performed on users in STAGED, ACTIVE or RECOVERY status that have a valid password credential

Request
path Parameters
userId
required
string

ID of an existing Okta user

Request Body schema: application/json
required
object (PasswordCredential)

When a user has a valid password, imported hashed password, or password hook, and a response object contains a 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).

object (PasswordCredentialHash)

Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a Password object when creating or updating a user, but not for other operations. See Create User with Imported Hashed Password for information on using this object when creating a user. When updating a user with a hashed password, the user must be in the STAGED status.

algorithm
string (PasswordCredentialHashAlgorithm)

The algorithm used to generate the hash using the password (and salt, when applicable).

Enum: "BCRYPT" "MD5" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)

Algorithm used to generate the key. Only required for the PBKDF2 algorithm.

Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer

The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.

keySize
integer

Size of the derived key in bytes. Only required for PBKDF2 algorithm.

salt
string

Only required for salted hashes. For BCRYPT, this specifies Radix-64 as the encoded salt used to generate the hash, which must be 22 characters long. For other salted hashes, this specifies the Base64-encoded salt used to generate the hash.

saltOrder
string

Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.

value
string

For SHA-512, SHA-256, SHA-1, MD5, and PBKDF2, this is the actual base64-encoded hash of the password (and salt, if used). This 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 the salt to the password, depending on the saltOrder. If a salt was not used in the source system, then this should just be the 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.

workFactor
integer [ 1 .. 20 ]

Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.

object (PasswordCredentialHook)

Specify a password import inline hook to trigger verification of the user's password the first time the user logs in. This allows an existing password to be imported into Okta directly from some other store. See Create User with Password Hook for information on using this object when creating a user.

type
string

The type of password inline hook. Currently, must be set to default.

value
string <password>

Specifies the password for a user. The Password Policy validates this password.