POST /api/v1/users

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 User Scenario Creations section in the Users API description.

Servers

https://{yourOktaDomain}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Query parameters

Name Type Required Description

Name	Type	Required	Description
`provider`	Boolean	No	Indicates whether to create a User with a specified authentication provider Default value: false
`activate`	Boolean	No	Executes an activation lifecycle operation when creating the User Default value: true
`nextLogin`	String	No	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. Possible values: `"changePassword"`

provider

Boolean

Indicates whether to create a User with a specified authentication provider

Default value: false

activate

Boolean

Executes an activation lifecycle operation when creating the User

Default value: true

nextLogin

String

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.

Possible values:

"changePassword"

Request body fields

Name	Type	Required	Description
`groupIds[]`	Array	No
`profile`	Object	Yes	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.
`profile.honorificSuffix`	String	No	Honorific suffix(es) of the User
`profile.postalAddress`	String	No	Mailing address component of the User's address
`profile.userType`	String	No	The property used to describe the organization-to-user relationship, such as employee or contractor
`profile.department`	String	No	Name of the User's department
`profile.displayName`	String	No	Name of the User suitable for display to end users
`profile.state`	String	No	The state or region component of the User's address (`region`)
`profile.zipCode`	String	No	The ZIP code or postal code component of the User's address (`postalCode`)
`profile.city`	String	No	The city or locality of the User's address (`locality`)
`profile.middleName`	String	No	The middle name of the user
`profile.timezone`	String	No	The User's time zone
`profile.costCenter`	String	No	Name of the cost center assigned to a user
`profile.email`	String	No	The primary email address of the user. For validation, see RFC 5322 Section 3.2.3.
`profile.employeeNumber`	String	No	The organization or company assigned unique identifier for the user
`profile.preferredLanguage`	String	No	The User's preferred written or spoken language. For validation, see RFC 7231 Section 5.3.5.
`profile.locale`	String	No	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.
`profile.title`	String	No	The User's title, such as Vice President
`profile.secondEmail`	String	No	The secondary email address of the User typically used for account recovery. For validation, see RFC 5322 Section 3.2.3.
`profile.managerId`	String	No	The `id` of the User's manager
`profile.division`	String	No	Name of the User's division
`profile.streetAddress`	String	No	The full street address component of the User's address
`profile.manager`	String	No	The `displayName` of the User's manager
`profile.nickName`	String	No	The casual way to address the User in real life
`profile.organization`	String	No	Name of the the User's organization
`profile.countryCode`	String	No	The country name component of the User's address (`country`). For validation, see ISO 3166-1 alpha 2 "short" code format.
`profile.honorificPrefix`	String	No	Honorific prefix(es) of the user, or title in most Western languages
`profile.lastName`	String	No	The family name of the User (`familyName`)
`profile.mobilePhone`	String	No	The mobile phone number of the user
`profile.firstName`	String	No	Given name of the User (`givenName`)
`profile.login`	String	No	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
`profile.primaryPhone`	String	No	The primary phone number of the User such as a home number
`profile.profileUrl`	String	No	The URL of the User's online profile. For example, a web page. See URL.
`realmId`	String	No	The ID of the Realm in which the User is residing
`credentials`	Object	No	Specifies primary authentication and recovery credentials for a User. Credential types and requirements vary depending on the provider and security policy of the org.
`credentials.provider`	Object	No	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.
`credentials.provider.name`	String	No	The name of the authentication provider
`credentials.provider.type`	String	No	The type of authentication provider Possible values: `"ACTIVE_DIRECTORY"` `"OKTA"` `"LDAP"` `"FEDERATION"` `"IMPORT"` `"SOCIAL"`
`credentials.recovery_question`	Object	No	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.
`credentials.recovery_question.answer`	String	No	The answer to the recovery question
`credentials.recovery_question.question`	String	No	The recovery question
`credentials.password`	Object	No	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.
`credentials.password.hash`	Object	No	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.
`credentials.password.hash.digestAlgorithm`	String	No	Algorithm used to generate the key. Only required for the PBKDF2 algorithm. Possible values: `"SHA512_HMAC"` `"SHA256_HMAC"`
`credentials.password.hash.keySize`	Integer	No	Size of the derived key in bytes. Only required for PBKDF2 algorithm.
`credentials.password.hash.algorithm`	String	No	The algorithm used to generate the hash using the password (and salt, when applicable). Possible values: `"BCRYPT"` `"PBKDF2"` `"MD5"` `"SHA-256"` `"SHA-512"` `"SHA-1"`
`credentials.password.hash.iterationCount`	Integer	No	The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.
`credentials.password.hash.value`	String	No	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.
`credentials.password.hash.saltOrder`	String	No	Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.
`credentials.password.hash.workFactor`	Integer	No	Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.
`credentials.password.hash.salt`	String	No	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.
`credentials.password.hook`	Object	No	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.
`credentials.password.hook.type`	String	No	The type of password inline hook. Currently, must be set to default.
`credentials.password.value`	String	No	Specifies the password for a user. The Password Policy validates this password.
`type`	Object	No	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.
`type.id`	String	No	The ID of the User Type

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.