Users

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

List all Users
CORS
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": {
      },
    • "_links": {}
    }
]
Create a User
CORS
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
CORS
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
CORS
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
CORS
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
CORS
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
CORS
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
CORS
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
CORS
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",
    • "issuer": "https://my_test_okta_org.oktapreview.com",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "scopeId": "okta.users.read",
    • "source": "ADMIN",
    • "status": "ACTIVE",
    • "userId": "string",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
Revoke all Grants for a Client
CORS
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
CORS
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
CORS
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
CORS
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
CORS
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
CORS
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
CORS
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.


 
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


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/credentials/change_recovery_question
Request samples 
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "provider": { },
  • "recovery_question": {
    • "answer": "string",
    • "question": "string"
    }
}
Response samples 
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      }
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "question": "string"
    }
}
Initiate Forgot Password
CORS
OAuth 2.0: okta.users.manage
Initiates the forgot password flow. Generates a one-time token (OTT) that can be used to reset a user's password.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
sendEmail
boolean
 Default:  true
 
Responses 
200
Reset url


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/credentials/forgot_password
Request samples 
Response samples 
application/json
{
  • "resetPasswordUrl": "string"
}
Reset Password with Recovery Question
CORS
OAuth 2.0: okta.users.manage
Resets the user's password to the specified password if the provided answer to the recovery question is correct


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
sendEmail
boolean
 Default:  true
 
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 (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


 
Responses 
200
Credentials


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/credentials/forgot_password_recovery_question
Request samples 
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      },
    • "value": "pa$$word"
    },
  • "provider": { },
  • "recovery_question": {
    • "answer": "string",
    • "question": "string"
    }
}
Response samples 
application/json
{
  • "password": {
    • "hash": {
      },
    • "hook": {
      }
    },
  • "provider": {
    • "name": "string",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "recovery_question": {
    • "question": "string"
    }
}
List all User Grants
CORS
OAuth 2.0: okta.users.read
Lists all grants for the specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
scopeId
string
 
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}/grants
Request samples 
Response samples 
application/json
[
  • {
    • "clientId": "string",
    • "created": "2019-08-24T14:15:22Z",
    • "createdBy": {
      },
    • "id": "string",
    • "issuer": "https://my_test_okta_org.oktapreview.com",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "scopeId": "okta.users.read",
    • "source": "ADMIN",
    • "status": "ACTIVE",
    • "userId": "string",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
Revoke all User Grants
CORS
OAuth 2.0: okta.users.manage
Revokes all grants for a specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/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": [ ]
}
Retrieve a User Grant
CORS
OAuth 2.0: okta.users.read
Retrieves a grant for the specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
grantId
required
string
Grant ID


 
 Example:  iJoqkwx50mrgX4T9LcaH
query Parameters
expand
string
 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/grants/{grantId}
Request samples 
Response samples 
application/json
{
  • "clientId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "createdBy": {
    • "id": "string",
    • "type": "User"
    },
  • "id": "string",
  • "issuer": "https://my_test_okta_org.oktapreview.com",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "scopeId": "okta.users.read",
  • "source": "ADMIN",
  • "status": "ACTIVE",
  • "userId": "string",
  • "_embedded": {
    • "scope": {
      }
    },
  • "_links": {
    • "self": {
      },
    • "app": {
      },
    • "client": {
      }
    }
}
Revoke a User Grant
CORS
OAuth 2.0: okta.users.manage
Revokes one grant for a specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
grantId
required
string
Grant ID


 
 Example:  iJoqkwx50mrgX4T9LcaH
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/grants/{grantId}
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 Groups
CORS
OAuth 2.0: okta.users.read
Lists all groups of which the user is a member


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
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  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/groups
Request samples 
Response samples 
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "objectClass": [
      ],
    • "profile": {
      },
    • "type": "APP_GROUP",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
List all Identity Providers
OAuth 2.0: okta.users.read
Lists the IdPs associated with the user


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}/idps
Request samples 
Response samples 
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "issuerMode": "CUSTOM_URL",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "name": "string",
    • "policy": {
      },
    • "properties": {
      },
    • "protocol": {
      },
    • "status": "ACTIVE",
    • "type": "AgentlessDSSO",
    • "_links": {
      }
    }
]
Activate a User
CORS
OAuth 2.0: okta.users.manage
Activates a user. This operation can only be performed on users with a STAGED or DEPROVISIONED status.
Activation of a user is an asynchronous operation. The user will have the transitioningToStatus
property with a value of ACTIVE during activation to indicate that the user hasn't completed the asynchronous operation.
The user will have a status of ACTIVE when the activation process is complete.




Multibrand and User activation

If you want to send a branded User Activation email, change the subdomain of your request to the custom domain that's associated with the brand.
For example, change subdomain.okta.com to custom.domain.one. See Multibrand and custom domains.



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 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
sendEmail
required
boolean
 Default:  true
Sends an activation email to the user if true


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/activate
Request samples 
Response samples 
application/json
{
  • "activationToken": "string",
  • "activationUrl": "string"
}
Deactivate a User
CORS
OAuth 2.0: okta.users.manage
Deactivates a user. This operation can only be performed on users that do not have a DEPROVISIONED status. While the asynchronous operation (triggered by HTTP header Prefer: respond-async) is proceeding the user's transitioningToStatus property is DEPROVISIONED. The user's status is DEPROVISIONED when the deactivation process is complete.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
sendEmail
boolean
 Default:  false
 
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/deactivate
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": [ ]
}
Expire Password
CORS
OAuth 2.0: okta.users.manage
Expires a user's password and transitions the user to the status of PASSWORD_EXPIRED so that the user is required to change their password at their next login


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/expire_password
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": { }
    },
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "resetPassword": {
      },
    • "resetFactors": {
      },
    • "expirePassword": {
      },
    • "forgotPassword": {
      },
    • "changeRecoveryQuestion": {
      },
    • "deactivate": {
      },
    • "reactivate": {
      },
    • "changePassword": {
      },
    • "schema": {
      },
    • "suspend": {
      },
    • "unsuspend": {
      },
    • "unlock": {
      },
    • "type": {
      }
    }
}
Expire Password and Set Temporary Password
CORS
OAuth 2.0: okta.users.manage
Expires a user's password and transitions the user to the status of PASSWORD_EXPIRED so that the user is required to change their password at their next login, and also sets the user's password to a temporary password returned in the response


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
revokeSessions
boolean
 Default:  false
When set to true (and the session is a user session), all user sessions are revoked except the current session.


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/expire_password_with_temp_password
Request samples 
Response samples 
application/json
{
  • "tempPassword": "string"
}
Reactivate a User
CORS
OAuth 2.0: okta.users.manage
Reactivates a user.  This operation can only be performed on users with a PROVISIONED status.  This operation restarts the activation workflow if for some reason the user activation was not completed when using the activationToken from Activate User.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
sendEmail
boolean
 Default:  false
Sends an activation email to the user if true


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/reactivate
Request samples 
Response samples 
application/json
{
  • "activationToken": "string",
  • "activationUrl": "string"
}
Reset all Factors
CORS
OAuth 2.0: okta.users.manage
Resets all factors for the specified user. All MFA factor enrollments returned to the unenrolled state. The user's status remains ACTIVE. This link is present only if the user is currently enrolled in one or more MFA factors.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
removeRecoveryEnrollment
boolean
 Default:  false
If true, removes the phone number as both a recovery method and a Factor. Supported Factors: sms and call


 
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/reset_factors
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": [ ]
}
Generate a Reset Password Token
CORS
OAuth 2.0: okta.users.manage
Generates a one-time token (OTT) that can be used to reset a user's password.  The OTT link can be automatically emailed to the user or returned to the API caller and distributed using a custom flow.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
sendEmail
required
boolean
 
revokeSessions
boolean
 Default:  false
When set to true (and the session is a user session), all user sessions are revoked except the current session.


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/reset_password
Request samples 
Response samples 
application/json
{
  • "resetPasswordUrl": "string"
}
Suspend a User
CORS
OAuth 2.0: okta.users.manage
Suspends a user.  This operation can only be performed on users with an ACTIVE status.  The user will have a status of SUSPENDED when the process is complete.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/suspend
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": [ ]
}
Unlock a User
CORS
OAuth 2.0: okta.users.manage
Unlocks a user with a LOCKED_OUT status or unlocks a user with an ACTIVE status that is blocked from unknown devices. Unlocked users have an ACTIVE status and can sign in with their current password.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/unlock
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": [ ]
}
Unsuspend a User
CORS
OAuth 2.0: okta.users.manage
Unsuspends a user and returns them to the ACTIVE state.  This operation can only be performed on users that have a SUSPENDED status.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/unsuspend
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": [ ]
}
Create a Linked Object for two Users
CORS
OAuth 2.0: okta.users.manage
Creates a Linked Object for two users


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
primaryRelationshipName
required
string
 
primaryUserId
required
string
id of primary User


 
 Example:  ctxeQ5JnAVdGFBB7Zr7W
Responses 
204
Success


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/users/{userId}/linkedObjects/{primaryRelationshipName}/{primaryUserId}
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 Linked Objects
CORS
OAuth 2.0: okta.users.read
Lists all linked objects for a user, relationshipName can be a primary or associated relationship name


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
relationshipName
required
string
 
query Parameters
after
string
 
limit
integer <int32> 
 Default:  -1
 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/linkedObjects/{relationshipName}
Request samples 
Response samples 
application/json
[
  • { }
]
Delete a Linked Object
CORS
OAuth 2.0: okta.users.manage
Deletes linked objects for a user, relationshipName can be ONLY a primary relationship name


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
relationshipName
required
string
 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/linkedObjects/{relationshipName}
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": [ ]
}
Revoke all User Sessions
CORS
OAuth 2.0: okta.users.manage
Revokes all active identity provider sessions of the user. This forces the user to authenticate on the next operation. Optionally revokes OpenID Connect and OAuth refresh and access tokens issued to the user.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
oauthTokens
boolean
 Default:  false
Revoke issued OpenID Connect and OAuth refresh and access tokens


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/sessions
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": [ ]
}