Users

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

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

User status

The following diagram shows the flow of user status: STAGED, PROVISIONED, ACTIVE, RECOVERY, LOCKED_OUT, PASSWORD_EXPIRED, or DEPROVISIONED

User creation scenarios

The following table describes the user experience and expectation of user status and welcome screen, depending on which options (security question and answer, password, and activate query) are defined during user creation.

User creation details and outcomes

Security Q & A Password Activate Query Parameter User Status Login Credential Welcome Screen
FALSE STAGED
TRUE PROVISIONED or ACTIVE One-Time Token (Email) or Email X
X FALSE STAGED
X TRUE PROVISIONED or ACTIVE One-Time Token (Email) or Email X
X FALSE STAGED
X TRUE ACTIVE Password X
X X FALSE STAGED
X X TRUE ACTIVE Password

Creating users with a FEDERATION or SOCIAL provider sets the user status to either ACTIVE or STAGED based on the activate query parameter since these two providers don't support a password or recovery_question credential.

More information about the use cases are in the following sections and in the examples for Create a user.

Create user with Optional Password enabled

When Optional Password is enabled, the user status following user creation can be affected by the enrollment policy. See Create an authenticator enrollment policy. Based on the group memberships that are specified when the user is created, a password may or may not be required to make the user's status ACTIVE.

If the enrollment policy that applies to the user (as determined by the groups assigned to the user) specifies that the Password authenticator is required, then in the case where the user is created without a password, the user is in the PROVISIONED status and a One-Time Token is sent to the user through email. If the user is created with a password, then their status is set to ACTIVE, and they can immediately sign in using their Password authenticator.

If the user doesn't have an enrolled authenticator, Okta sets the user to PROVISIONED and sends an activation link. The user must click the activation link before they can log in. The activation link provides a baseline assurance that can be used to enroll in other authenticators. If the user has one or more enrolled authenticators at activation time, they’re set to ACTIVE and can log in directly.

Create user without credentials

Creates a user without a password or a recovery question & answer.

If appropriate, when the user is activated, an email is sent to the user with an activation token that the user can use to complete the activation process. This is the default flow for new user registration using the administrator UI.

Create user with recovery question

Creates a user without a password.

When the user is activated, an email is sent to the user with an activation token that can be used to complete the activation process. This flow is useful if migrating users from an existing user store.

Create user with password

Creates a user without a recovery question & answer.

The new user is able to sign in after activation with the assigned password. This flow is common when developing a custom user registration experience.

Important: Do not generate or send a one-time activation token when activating users with an assigned password. Users should sign in with their assigned password.

Create User with imported hashed password

Creates a user with a specified hashed password.

The new user is able to sign in after activation with the specified password.

This flow is common when migrating users from another data store in cases where we want to allow the users to retain their current passwords.

Important: Do not generate or send a one-time activation token when activating users with an imported password. Users should login with their imported password.

Create user with password import inline hook

Creates a user with a Password Hook object specifying that a password inline hook should be used to handle password verification.

The password inline hook is triggered to handle verification of the end user's password the first time the user tries to sign in, with Okta calling the password inline hook to check that the password the user supplied is valid. If the password is valid, Okta stores the hash of the password that was provided and can authenticate the user independently from then on. See Password import inline hook for more details.

The new user is able to sign in after activation with the valid password. This flow supports migrating users from another data store in cases where we wish to allow the users to retain their current passwords.

Important: Don't generate or send a one-time activation token when activating users with an password inline hook. Users should sign in with their existing password to be imported using the password import inline hook.

Create user with password & recovery question

Creates a new user with a password and recovery question & answer.

The new user is able to log in with the assigned password after activation. This flow is common when developing a custom user-registration experience.

Important: Don't generate or send a one-time activation token when activating users with an assigned password. Users should login with their assigned password.

Create user with authentication provider

Creates a new passwordless user with a SOCIAL or FEDERATION authentication provider that must be authenticated via a trusted Identity Provider.

Create user in Group

Creates a user that is added to the specified groups upon creation.

Use this in conjunction with other create operations for a Group Administrator that is scoped to create users only in specified groups. The request may specify up to 20 group ids. (This limit applies only when creating a user. The user may later be added to more groups.)

Create user with non-default user type

Creates a user with a specified user type (see User Types). The type specification may be included with any of the above Create user operations; this example demonstrates creating a user without credentials. The user type determines which Schema applies to that user. After a user has been created, the user can be assigned a different user type only by an admin via a full replacement PUT operation.

The links object specifies link relations. See _links.

Note: This links object is different from Linked Objects.

Individual users versus collection of users

For an individual user result, the links object contains a full set of link relations available for that user as determined by your policies. For a collection of users, the links object contains only the self link. Operations that return a collection of users include List all users and List all member users.

The following table shows some links that may be available on a user, as determined by your policies:

Link Relation Type Description
self A self-referential link to this user
activate Lifecycle action to activate the user
deactivate Lifecycle action to deactivate the user
suspend Lifecycle action to suspend the user
unsuspend Lifecycle action to unsuspend the user
resetPassword Lifecycle action to trigger a password reset
expirePassword Lifecycle action to expire the user's password
resetFactors Lifecycle action to reset all MFA factors
unlock Lifecycle action to unlock a locked-out user
forgotPassword Resets a user's password by validating the user's recovery credential.
changePassword Changes a user's password validating the user's current password
changeRecoveryQuestion Changes a user's recovery credential by validating the user's current password

List all users
CORS
OAuth 2.0: okta.users.read

Lists users in your org, with pagination in most cases.

A subset of users can be returned that match a supported filter expression or search criteria.

Request
query Parameters
q
string

Finds users who match the specified query. This doesn't support pagination.

This might not deliver optimal performance for large orgs, and is deprecated for such use cases. To ensure optimal performance, use a search parameter instead.

Use the q parameter for a simple lookup of users by name, for example when creating a people picker. The value of q is matched against firstName, lastName, or email. This performs a startsWith match, but this is an implementation detail and can change without notice. You don't need to specify firstName, lastName, or email.

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.

This requires URL encoding. For example, filter=lastUpdated gt "2013-06-01T00:00:00.000Z" is encoded as filter=lastUpdated%20gt%20%222013-06-01T00:00:00.000Z%22. Filtering is case-sensitive for attribute names and query values, while attribute operators are case-insensitive.

Filtering supports the following limited number of properties: status, lastUpdated, id, profile.login, profile.email, profile.firstName, and profile.lastName.

Additionally, filtering supports only the equal eq operator from the standard Okta API filtering semantics, except in the case of the lastUpdated property. This property can also use the inequality operators (gt, ge, lt, and le). For logical operators, only the logical operators and and or are supported. The not operator isn't supported. See Filtering and Operators.

Examples:
filter=status eq "LOCKED_OUT"
filter=profile.login eq "login@example.com"
filter=filter=lastUpdated gt "2013-06-01T00:00:00.000Z" and lastUpdated lt "2014-01-01T00:00:00.000Z"
filter=lastUpdated gt "2013-06-01T00:00:00.000Z" and (status eq "LOCKED_OUT" or status eq "RECOVERY")
search
string

Searches for users with a supported filtering expression for most properties. Okta recommends using this parameter for search for best performance. This operation supports pagination. Use an ID lookup for records that you update to ensure your results contain the latest data.

Property names in the search parameter are case sensitive, whereas operators (eq, sw, and so on) and string values are case insensitive. Unlike with user logins, diacritical marks are significant in search string values: a search for isaac.brock finds Isaac.Brock, but doesn't find a property whose value is isáàc.bröck. This operation requires URL encoding. For example, search=profile.department eq "Engineering" is encoded as search=profile.department%20eq%20%22Engineering%22.

Note: If you use the special character " within a quoted string, it must also be escaped \ and encoded. For example, search=profile.lastName eq "bob"smith" is encoded as search=profile.lastName%20eq%20%22bob%5C%22smith%22.

This operation searches many properties:

  • Any user profile property, including custom-defined properties
  • The top-level properties id, status, created, activated, statusChanged, and lastUpdated
  • The user type accessed as type.id

You can also use sortBy and sortOrder parameters. The ne (not equal) operator isn't supported, but you can obtain the same result by using lt ... or ... gt. For example, to see all users except those that have a status of STAGED, use (status lt "STAGED" or status gt "STAGED").

You can search properties that are arrays. If any element matches the search term, the entire array (object) is returned. Okta follows the SCIM Protocol Specification for searching arrays. You can search multiple arrays, multiple values in an array, as well as using the standard logical and filtering operators. See Filter.

Examples:
search=status eq "STAGED"
search=lastUpdated gt "2014-01-01T00:00:00.000Z"
search=id eq "00u1ero7vZFVEIYLWPBN"
search=profile.department eq "Engineering" and (created lt "2014-01-01T00:00:00.000Z" or status eq "ACTIVE")
search=profile.arrayAttr eq "arrayAttrVal1"
sortBy
string

Specifies field to sort by (for search queries only). This can be any single property, for example sortBy=profile.lastName. Users with the same value for the sortBy property will be ordered by id.

sortOrder
string

Specifies sort order asc or desc (for search queries only). Sorting is done in ASCII sort order (that is, by ASCII character value), but isn't case sensitive. sortOrder is ignored if sortBy is not present.

header Parameters
Content-Type
string

Specifies the media type of the resource. Optional okta-response value can be included for performance optimization.

Complex DelAuth configurations may degrade performance when fetching specific parts of the response, and passing this parameter can omit these parts, bypassing the bottleneck.

Enum values for okta-response:

  • omitCredentials: Omits the credentials subobject from the response.
  • omitCredentialsLinks: Omits the following HAL links from the response: Change Password, Change Recovery Question, Forgot Password, Reset Password, Reset Factors, Unlock.
  • omitTransitioningToStatus: Omits the transitioningToStatus field from the response.
Examples:
application/json; okta-response=omitCredentials,omitCredentialsLinks
application/json; okta-response="omitCredentials,omitCredentialsLinks, omitTransitioningToStatus"
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 org 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.




All responses return the created user. Activation of a user is an asynchronous operation. The system performs group reconciliation during activation and assigns the user to all apps via direct or indirect relationships (group memberships).


    

  • The user's transitioningToStatus property is ACTIVE during activation to indicate that the user hasn't completed the asynchronous operation.
    • 

  • The user's status is ACTIVE when the activation process is complete.
    • 



The user is emailed a one-time activation token if activated without a password.




Note: If the user is assigned to an app that is configured for provisioning, the activation process triggers downstream provisioning to the app.  It is possible for a user to sign in before these apps have been successfully provisioned for the user.






Important: Do not generate or send a one-time activation token when activating users with an assigned password. Users should sign in with their assigned password.




For more information about the various scenarios of creating a user listed in the examples, see the User creation scenarios section.


Request 
query Parameters
activate
boolean
 Default:  true
Executes an 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, if nextLogin=changePassword, a user is created, activated, and the password is set to EXPIRED. The user must change it the next time they sign in.


 Value: "changePassword"  
Request Body schema: application/json
required
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 Admin Console 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 can 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). For validation, see ISO 3166-1 alpha 2 "short" code format.


 
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 characters 
The unique identifier for the user (username). For validation, see Login pattern validation.


Every user within your Okta org must have a unique identifier for a login. This constraint applies to all users you import from other systems or applications such as Active Directory. Your organization is the top-level namespace to mix and match logins from all your connected applications or directories. Careful consideration of naming conventions for your login identifier will make it easier to onboard new applications in the future.


Logins are not considered unique if they differ only in case and/or diacritical marks. If one of your users has a login of Isaac.Brock@example.com, there cannot be another user whose login is isaac.brock@example.com, nor isáàc.bröck@example.com.


Okta has a default ambiguous name resolution policy for usernames that include @-signs. (By default, usernames must be formatted as email addresses and thus always include @-signs. You can remove that restriction using either the Admin Console or the Schemas API (opens new window).) Users can sign in with their non-qualified short name (for example: isaac.brock with username isaac.brock@example.com) as long as the short name is still unique within the organization.
maxLength: 100


 
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. For validation, see RFC 7231 Section 5.3.5.


 
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. For validation, see RFC 5322 Section 3.2.3.


 
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 (UserCredentialsWritable) 
Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the org.


 
object (PasswordCredential) 
Specifies a password for a user.


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).


For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.


 
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 the Create user with imported hashed password section in the Users API description. When updating a user with a hashed password, the usermust 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 signs in. This allows an existing password to be imported into Okta directly from some other store.


 
value
string <password> 
Specifies the password for a user. The password policy validates this password.


 
object (AuthenticationProviderWritable) 
Specifies the authentication provider that validates the user password credential. The user's current provider is managed by the Delegated Authentication settings in your org. See Create user with authentication provider.


 
name
string
The name of the authentication provider


 
type
string (AuthenticationProviderTypeWritable) 
The type of authentication provider


 Enum: Description
ACTIVE_DIRECTORY
Specifies a Microsoft Active Directory instance name as the name property


FEDERATION
Specifies a federated identity provider (such as a SAML IdP) that validates the user's password credentials. Doesn't support a password or recovery question credential. The user must authenticate through a trusted identity provider.


IMPORT
Specifies a hashed password that was imported from an external source


LDAP
Specifies the LDAP directory instance name as the name property


OKTA
Specifies the Okta identity provider


SOCIAL
Specifies an OIDC or third-party social identity provider. Doesn't support a password or recovery question credential. The user must authenticate through a trusted identity provider.


 
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 answer to the recovery question


 
question
string  [ 1 .. 100 ] 
The recovery question


 
groupIds
Array of strings
 
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
See Create user without credentials for description


{
  • "profile": {
    • "firstName": "Isaac",
    • "lastName": "Brock",
    • "email": "isaac.brock@example.com",
    • "login": "isaac.brock@example.com",
    • "mobilePhone": "555-415-1337"
    }
}
Response samples 
application/json
{}
Retrieve a user
CORS
OAuth 2.0: okta.users.read
Retrieves a user from your Okta org.


You can substitute me for the id to fetch the current user linked to an API token or session cookie.


    

  • The request returns the user linked to the API token that is specified in the Authorization header, not the user linked to the active session. Details of the admin user who granted the API token is returned.
    • 

  • When the end user has an active Okta session, it is typically a CORS request from the browser. Therefore, it's possible to retrieve the current user without the Authorization header.
    • 



When fetching a user by login or login shortname, URL encode the request parameter to ensure that special characters are escaped properly. Logins with a / character can only be fetched by id due to URL issues with escaping the / character. If you don't know a user's ID, you can use the List all users endpoint to find it.




Note: Some browsers block third-party cookies by default, which disrupts Okta functionality in certain flows. See Mitigate the impact of third-party cookie deprecation.




Request 
path Parameters
id
required
string
id, login, or login shortname (as long as it is unambiguous) of a user


 
query Parameters
expand
string
An optional parameter to include metadata in the _embedded attribute. Valid value: blocks


 
 Example:  expand=blocks
header Parameters
Content-Type
string
Specifies the media type of the resource. Optional okta-response value can be included for performance optimization.


Complex DelAuth configurations may degrade performance when fetching specific parts of the response, and passing this parameter can omit these parts, bypassing the bottleneck.


Enum values for okta-response:


    

  • omitCredentials: Omits the credentials subobject from the response.
    • 

  • omitCredentialsLinks: Omits the following HAL links from the response: Change Password, Change Recovery Question, Forgot Password, Reset Password, Reset Factors, Unlock.
    • 

  • omitTransitioningToStatus: Omits the transitioningToStatus field from the response.
    • 



  Examples: 
application/json; okta-response=omitCredentials,omitCredentialsLinks
application/json; okta-response="omitCredentials,omitCredentialsLinks, omitTransitioningToStatus"
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{id}
Request samples 
Response samples 
application/json
{
  • "id": "00ub0oNGTSWTBKOLGLNR",
  • "status": "ACTIVE",
  • "created": "2013-06-24T16:39:18.000Z",
  • "activated": "2013-06-24T16:39:19.000Z",
  • "statusChanged": "2013-06-24T16:39:19.000Z",
  • "lastLogin": "2013-06-24T17:39:19.000Z",
  • "lastUpdated": "2013-07-02T21:36:25.344Z",
  • "passwordChanged": "2013-07-02T21:36:25.344Z",
  • "profile": {
    • "login": "isaac.brock@example.com",
    • "firstName": "Isaac",
    • "lastName": "Brock",
    • "nickName": "issac",
    • "displayName": "Isaac Brock",
    • "email": "isaac.brock@example.com",
    • "secondEmail": "isaac@example.org",
    • "profileUrl": "http://www.example.com/profile",
    • "preferredLanguage": "en-US",
    • "userType": "Employee",
    • "organization": "Okta",
    • "title": "Director",
    • "division": "R&D",
    • "department": "Engineering",
    • "costCenter": "10",
    • "employeeNumber": "187",
    • "mobilePhone": "+1-555-415-1337",
    • "primaryPhone": "+1-555-514-1337",
    • "streetAddress": "301 Brannan St.",
    • "city": "San Francisco",
    • "state": "CA",
    • "zipCode": "94107",
    • "countryCode": "US"
    },
  • "credentials": {
    • "password": { },
    • "recovery_question": {
      },
    • "provider": {
      }
    },
  • "_links": {}
}
Update a user
CORS
OAuth 2.0: okta.users.manage
Updates a user's profile or credentials with partial update semantics.




Important: Use the POST method for partial updates. Unspecified properties are set to null with PUT.




profile and credentials can be updated independently or together with a single request.




Note: Currently, the user type of a user can only be changed via a full replacement PUT operation. If the request parameters of a partial update include the type element from the user object,
the value must match the existing type of the user. Only admins are permitted to change the user type of a user; end users are not allowed to change their own user type.






Note: To update a current user's profile with partial semantics, the /api/v1/users/me endpoint can be invoked.


A user can only update profile properties for which the user has write access. Within the profile, if the user tries to update the primary or the secondary email IDs, verification emails are sent to those email IDs, and the fields are updated only upon verification.




If you are using this endpoint to set a password, it sets a password without validating existing user credentials. This is an administrative operation. For operations that validate credentials, refer to the Reset Password, Forgot Password, and Change Password endpoints.


Request 
path Parameters
id
required
string
id, login, or login shortname (as long as it is unambiguous) of a user


 
query Parameters
strict
boolean
If true, validates against minimum age and history password policy


 
Request Body schema: application/json
required
object (UserCredentials) 
Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the org.


 
object (PasswordCredential) 
Specifies a password for a user.


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).


For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.


 
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 the Create user with imported hashed password section in the Users API description. When updating a user with a hashed password, the usermust 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 signs in. This allows an existing password to be imported into Okta directly from some other store.


 
value
string <password> 
Specifies the password for a user. The password policy validates this password.


 
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 answer to the recovery question


 
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 Admin Console 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 can 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). For validation, see ISO 3166-1 alpha 2 "short" code format.


 
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 characters 
The unique identifier for the user (username). For validation, see Login pattern validation.


Every user within your Okta org must have a unique identifier for a login. This constraint applies to all users you import from other systems or applications such as Active Directory. Your organization is the top-level namespace to mix and match logins from all your connected applications or directories. Careful consideration of naming conventions for your login identifier will make it easier to onboard new applications in the future.


Logins are not considered unique if they differ only in case and/or diacritical marks. If one of your users has a login of Isaac.Brock@example.com, there cannot be another user whose login is isaac.brock@example.com, nor isáàc.bröck@example.com.


Okta has a default ambiguous name resolution policy for usernames that include @-signs. (By default, usernames must be formatted as email addresses and thus always include @-signs. You can remove that restriction using either the Admin Console or the Schemas API (opens new window).) Users can sign in with their non-qualified short name (for example: isaac.brock with username isaac.brock@example.com) as long as the short name is still unique within the organization.
maxLength: 100


 
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. For validation, see RFC 7231 Section 5.3.5.


 
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. For validation, see RFC 5322 Section 3.2.3.


 
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/{id}
Request samples 
application/json
{
  • "profile": {
    • "firstName": "Isaac",
    • "email": "isaac.brock@update.example.com",
    • "mobilePhone": "555-415-1337"
    }
}
Response samples 
application/json
{
  • "id": "00ub0oNGTSWTBKOLGLNR",
  • "status": "ACTIVE",
  • "created": "2013-06-24T16:39:18.000Z",
  • "activated": "2013-06-24T16:39:19.000Z",
  • "statusChanged": "2013-06-24T16:39:19.000Z",
  • "lastLogin": "2013-06-24T17:39:19.000Z",
  • "lastUpdated": "2013-07-02T21:36:25.344Z",
  • "passwordChanged": "2013-07-02T21:36:25.344Z",
  • "profile": {
    • "login": "isaac.brock@example.com",
    • "firstName": "Isaac",
    • "lastName": "Brock",
    • "nickName": "issac",
    • "displayName": "Isaac Brock",
    • "email": "isaac.brock@example.com",
    • "secondEmail": "isaac@example.org",
    • "profileUrl": "http://www.example.com/profile",
    • "preferredLanguage": "en-US",
    • "userType": "Employee",
    • "organization": "Okta",
    • "title": "Director",
    • "division": "R&D",
    • "department": "Engineering",
    • "costCenter": "10",
    • "employeeNumber": "187",
    • "mobilePhone": "+1-555-415-1337",
    • "primaryPhone": "+1-555-514-1337",
    • "streetAddress": "301 Brannan St.",
    • "city": "San Francisco",
    • "state": "CA",
    • "zipCode": "94107",
    • "countryCode": "US"
    },
  • "credentials": {
    • "password": { },
    • "recovery_question": {
      },
    • "provider": {
      }
    },
  • "_links": {}
}
Replace a user
CORS
OAuth 2.0: okta.users.manage
Replaces a user's profile, credentials, or both using strict-update semantics.


All profile properties must be specified when updating a user's profile with a PUT method. Any property not specified in the request is deleted.




Important: Don't use a PUT method for partial updates.




Request 
path Parameters
id
required
string
id, login, or login shortname (as long as it is unambiguous) of a user


 
query Parameters
strict
boolean
If true, validates against minimum age and history password policy


 
Request Body schema: application/json
required
object (UserCredentials) 
Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the org.


 
object (PasswordCredential) 
Specifies a password for a user.


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).


For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.


 
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 the Create user with imported hashed password section in the Users API description. When updating a user with a hashed password, the usermust 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 signs in. This allows an existing password to be imported into Okta directly from some other store.


 
value
string <password> 
Specifies the password for a user. The password policy validates this password.


 
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 answer to the recovery question


 
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 Admin Console 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 can 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). For validation, see ISO 3166-1 alpha 2 "short" code format.


 
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 characters 
The unique identifier for the user (username). For validation, see Login pattern validation.


Every user within your Okta org must have a unique identifier for a login. This constraint applies to all users you import from other systems or applications such as Active Directory. Your organization is the top-level namespace to mix and match logins from all your connected applications or directories. Careful consideration of naming conventions for your login identifier will make it easier to onboard new applications in the future.


Logins are not considered unique if they differ only in case and/or diacritical marks. If one of your users has a login of Isaac.Brock@example.com, there cannot be another user whose login is isaac.brock@example.com, nor isáàc.bröck@example.com.


Okta has a default ambiguous name resolution policy for usernames that include @-signs. (By default, usernames must be formatted as email addresses and thus always include @-signs. You can remove that restriction using either the Admin Console or the Schemas API (opens new window).) Users can sign in with their non-qualified short name (for example: isaac.brock with username isaac.brock@example.com) as long as the short name is still unique within the organization.
maxLength: 100


 
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. For validation, see RFC 7231 Section 5.3.5.


 
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. For validation, see RFC 5322 Section 3.2.3.


 
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


put/api/v1/users/{id}
Request samples 
application/json
{
  • "credentials": {
    • "password": {
      },
    • "recovery_question": {
      },
    • "provider": {
      }
    },
  • "profile": {
    • "firstName": "Isaac",
    • "lastName": "Brock",
    • "email": "isaac.brock@example.com",
    • "login": "isaac.brock@example.com",
    • "mobilePhone": "555-415-1337"
    }
}
Response samples 
application/json
{
  • "id": "00ub0oNGTSWTBKOLGLNR",
  • "status": "ACTIVE",
  • "created": "2013-06-24T16:39:18.000Z",
  • "activated": "2013-06-24T16:39:19.000Z",
  • "statusChanged": "2013-06-24T16:39:19.000Z",
  • "lastLogin": "2013-06-24T17:39:19.000Z",
  • "lastUpdated": "2013-07-02T21:36:25.344Z",
  • "passwordChanged": "2013-07-02T21:36:25.344Z",
  • "profile": {
    • "login": "isaac.brock@example.com",
    • "firstName": "Isaac",
    • "lastName": "Brock",
    • "nickName": "issac",
    • "displayName": "Isaac Brock",
    • "email": "isaac.brock@example.com",
    • "secondEmail": "isaac@example.org",
    • "profileUrl": "http://www.example.com/profile",
    • "preferredLanguage": "en-US",
    • "userType": "Employee",
    • "organization": "Okta",
    • "title": "Director",
    • "division": "R&D",
    • "department": "Engineering",
    • "costCenter": "10",
    • "employeeNumber": "187",
    • "mobilePhone": "+1-555-415-1337",
    • "primaryPhone": "+1-555-514-1337",
    • "streetAddress": "301 Brannan St.",
    • "city": "San Francisco",
    • "state": "CA",
    • "zipCode": "94107",
    • "countryCode": "US"
    },
  • "credentials": {
    • "password": { },
    • "recovery_question": {
      },
    • "provider": {
      }
    },
  • "_links": {}
}
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 can't be recovered!


This operation on a user that hasn't been deactivated causes that user to be deactivated. A second delete operation is required to delete the user.




Note: You can also perform user deletion asynchronously. To invoke asynchronous user deletion, pass an HTTP header Prefer: respond-async with the request.




This header is also supported by user deactivation, which is performed if the delete endpoint is invoked on a user that hasn't been deactivated.


Request 
path Parameters
id
required
string
id, login, or login shortname (as long as it is unambiguous) of a user


 
query Parameters
sendEmail
boolean
 Default:  false
Sends a deactivation email to the admin if true


 
header Parameters
Prefer
string
 Value: "respond-async"  
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{id}
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


 
 Example:  00ub0oNGTSWTBKOLGLNR
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"
    }
]