Creates a user in Cloud Directory.

post https://{tenanturl}/v2.0/Users

Entitlement required: manageUserGroups (Manage users and groups), or manageAllUserGroups (Synchronize users and groups), or manageUserStandardGroups (Manage users and standard groups), or manageUsers (Manage all users), or manageUsersInStandardGroups (Manage users in standard groups).
Note: You only need one entitlement, but you can have more than one.

The users are created for a specific tenant that is specified in the request. Users are either created to use Cloud Directory as an identity source or as a just-in-time provisioning sequence when the user is authenticated at a remote identity source such as an enterprise authentication.

By default, an email is sent with the password to the user that was created, unless its a federated user. Federated users do not get an email notification. The email templates for branding are at "notifications/user_management/profile/{locale}/account_created_email.xml" and "notifications/user_management/profile/{locale}/account_created_email_with_no_password.xml". Pass in the themeId query parameter to brand the email templates for notifications. To turn off email notifications, send the notifications option "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification": {"notifyType":"NONE"} in the payload.

If custom password intelligence warning is enabled and a password is provided that is listed in it, the 201 response includes the header 'isv-dictionary-policy' with the value: 'WARNLOCAL'.
If X-Force password intelligence warning is enabled and a password is provided that is listed in it, the 201 response includes the header 'isv-dictionary-policy' with the value: 'WARNGLOBAL'.
If custom password intelligence prevention is enabled and a password is provided that is listed in it, the 400 response can include the header 'isv-dictionary-policy' with the value: 'ENFORCELOCAL'. The corresponding error status is 'PWD_IN_DICTIONARY'.
If X-Force password intelligence prevention is enabled and a password is provided that is listed in it, the 400 response can include the header 'isv-dictionary-policy' with the value: 'ENFORCEGLOBAL'. The corresponding error status is 'PWD_IN_GLOBAL_DICTIONARY'.

Query Params

hashed

string

The comma-separated list of attributes whose values are to be hashed.

themeId

string

The identifier of the theme that you want to apply.

Body Params

The user object that contains the attributes for the user that is to be created.

schemas

array of strings

required

An array of strings that contain the URIs that indicate the namespaces of the SCIM schemas that define the attributes in the current JSON structure.
The schemas ""urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:ibm:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" and "urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification" are valid. The core user schema is required.

schemas*

userName

string

required

The unique identifier for the user that is typically used by the user to directly authenticate to the service provider. It is often displayed to the user as their unique identifier within the system (as opposed to the id or externalId attributes, which are generally opaque and not user-friendly identifiers). Each user must include a non-empty userName value. This identifier must be unique across the service consumer's entire set of Users. It must be a stable ID that does not change when the same user is returned in subsequent requests. Maximum length is 256 characters.

externalId

string

The unique identifier for the resource that is defined by the provisioning client. It identifies a resource between the provisioning client and the service provider. The client can use a filter to locate the resource with that identifier from the provisioning domain. Maximum length is 240 characters.

title

string

The user's title, such as "Vice President." Maximum length is 128 characters.

password

string

The user's clear text password. This attribute is used to specify an initial password when a new user is created or to reset an existing user's password. Maximum length is 4096 characters. If the password contains extended ASCII characters then you must add charset=utf-8 in the Content-Type header when making a REST API call. Cannot begin with the > character and end with the < character.

name

object

displayName

string

The name of the user that is displayed to users. Each user returned may include a non-empty displayName value. Typically it is the full name of the user that is being described, for example, Babs Jensen or Ms. Barbara J Jensen. However, if that information is unavailable, a username or handle can be used, for example, bjensen. The value is the primary textual label by which this User is normally displayed by the service provider when presenting information to users. Maximum length is 128 characters.

preferredLanguage

string

The language code identifying the preferred language of this identity, for example, en-us or fr-ca. Maximum length is 5 characters.

active

boolean

A Boolean value that indicates the user's administrative status. The definitive meaning of this attribute is determined by the service provider. For example, a value of true indicates that the user can log in, while a value of false indicates that the user's account has been suspended. If not specified, the value defaults to true.

emails

array of objects

A list of email addresses that can be used to create a user.

emails

addresses

array of objects

A list of addresses that can be used to create a user.

addresses

phoneNumbers

array of objects

A list of phone numbers that can be used to create a user.

phoneNumbers

urn:ietf:params:scim:schemas:extension:ibm:2.0:User

object

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

object

urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification

object

Headers

usershouldnotneedtoresetpassword

string

Defaults to false

If set to true, the user is not required to change the password after login.
Only honored when the password element of UserV2 is set.

Responses

Response body

object

schemas

array of strings

required

An array of strings that contain the URIs that indicate the namespaces of the SCIM schemas that define the attributes in the current JSON structure. The schemas "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:ibm:2.0:User" and "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" are returned in the response.

schemas*

string

required

The unique identifier for the resource as defined by the service. This attribute is read-only and ise sent by the service. Any value that is specified for this attribute in the JSON POST or PUT request payload is ignored.

externalId

string

A unique identifier for the resource that is defined by the provisioning client. It identifies a resource between the provisioning client and the service provider. The client can use a filter to locate the resource with an identifier from the provisioning domain.

meta

object

resourceType

string

The field that indicates the type of resource.

created

string

A DateTime string that indicates when the resource was created.

lastModified

string

A DateTime string that indicates when the resource was last modified.

location

string

The URI of the resource that is being returned.

deactivated

string

A readonly string that indicates why the account is deactivated. Valid values are "api", "timestamp", and "cleanup". The value "api" means that the user was deactivated by using an API. The value "timestamp" means that the user was deactivated by the system because the account expired. The value "cleanup" means that the user was deactivated by the system during account cleanup processing.

api timestamp cleanup

userName

string

required

The unique identifier for the user that is typically used by the user to directly authenticate to the service provider. It is often displayed to the user as their unique identifier within the system (as opposed to the id or externalId attributes, which are generally opaque and not user-friendly identifiers). Each user must include a non-empty userName value. This identifier must be unique across the service consumer's entire set of users. It must be a stable ID that does not change when the same user is returned in subsequent requests.

title

string

The user's title, such as "Vice President."

name

object

required

formatted

string

The full name of the user that includes all user names, middle names, and suffixes, that are formatted for display. This value is returned by the service provider if it is not part of the POST or PUT payloads. If the POST or PUT JSON payload contains the value for this attribute, the value in the payload takes precedence. Maximum length is 240 characters.

familyName

string

The family name of the user, or the last name in most Western languages. For example, Jensen is the family name from the full name Ms. Barbara J Jensen, PhD. Maximum length is 80 characters.

givenName

string

The given name of the user, or first name in most Western languages. For example, Barbara is the given name from the full name Ms. Barbara J Jensen, PhD. Maximum length is 80 characters.

middleName

string

The middle name(s) of the user. Maximum length is 80 characters.

displayName

string

The name of the user that is displayed to users. Each user returned may include a non-empty displayName value. Typically it is the full name of the user being described, for example, Babs Jensen or Ms. Barbara J Jensen. However, if that information is unavailable, a username or handle can be used, for example, bjensen. The value is the primary textual label by which this user is normally displayed by the service provider when presenting information to users.

preferredLanguage

string

The language code identifying the preferred language of this identity, for example, en-us or fr-ca.

active

boolean

A Boolean value that indicates the user's administrative status. The definitive meaning of this attribute is determined by the service provider. For example, a value of true indicates that the user can, log in, while a value of false indicates that the user's account has been suspended. If not specified, the value defaults to true.

emails

array of objects

required

A list of email addresses that are associated with the user. Only one is supported.

emails*

object

value

string

required

The e-mail addresses for the user. The value is canonicalized by the service provider. For example, bjensen@example.com instead of bjensen@EXAMPLE.COM. Must be RFC 2822 compliant. Maximum length is 128 characters.

type

string

required

A label that indicates the attribute function; for example, "work". Only a single email is allowed.

work

addresses

array of objects

required

A list of addresses that are associated with the user.

addresses*

object

locality

string

The city or locality component. Maximum length is 128 characters.

country

string

The country name component. Maximum length is 128 characters.

type

string

A label that indicates the attribute's function; for example, "work" or "home".

work

streetAddress

string

The street address. Maximum length is 128 characters.

postalCode

string

The postal code. Maximum length is 40 characters.

formatted

string

The formatted value of the address. Maximum length is 500 characters.

primary

boolean

Indicates whether this is address is the primary address for correspondence.

region

string

The region. Maximum length is 128 characters.

phoneNumbers

array of objects

A list of phone numbers that are associated with the user.

phoneNumbers

object

value

string

required

A list of phone numbers that are associated with the user. The value is be canonicalized by the service provider according to format in RFC3966, for example, "tel:+1-201-555-0123". Canonical type values are work, home, mobile, fax, and pager. Maximum length is 32 characters.

type

string

required

A label that indicates the attribute's function; for example, "work" or "home".

work home mobile pager fax

groups

array of objects

The list of groups that the user belongs to. Any value that is specified for this attribute in the JSON POST or PUT request payload is ignored. Group membership is managed by using the /Groups API.

groups

object

displayName

string

The display name of the group that the user belongs to.

string

The identifier of the group that the user belongs to.

value

string

required

A sub-attr required by the SCIM specification that contains the "id" of the SCIM resource the user belongs to.

$ref

string

required

A sub-attr required by the SCIM specification the contains the URI of the SCIM resource the user belongs to.

urn:ietf:params:scim:schemas:extension:ibm:2.0:User

object

userCategory

string

The user category.

regular federated

emailVerified

string

A timestamp that indicates when the user's email was verified.

realm

string

The realm to which the user belongs. It is always "cloudIdentityRealm" for non-federated users.

unqualifiedUserName

string

An unqualified, federated user name. This field is read-only.

twoFactorAuthentication

boolean

Indicates whether two factory authentication is required. It defaults to "false" if not provided.

pwdReset

boolean

Indicates whether the password is reset for the current user entry. This value is read-only.

pwdChangedTime

int64

Indicates the time when the password was changed for the current user entry. This value is read-only.

pwdAccountLockedTime

string

A field that indicates the timestamp at which the user's password was locked. The value of this field is in milliseconds and is read-only.

pwdExpirationWarned

string

A field that indicates the timestamp at which the user's password expiration is set. The value of this field is in milliseconds and is read-only.

pwdFailureTime

array of strings

A field that indicates a list of timestamps at which the user attempted to log in with the wrong password The value of this field is in milliseconds and is read-only.

pwdFailureTime

pwdGraceUseTime

array of strings

A field that indicates a list of timestamps at which the user attempted to see extended or grace time. The value of this field is in milliseconds and is read-only.

pwdGraceUseTime

delegate

string

The "id" of the entry to which approval and re-certification records assigned to this identity will be delegated.

customAttributes

array of objects

The custom attributes for the user. For the GET /Users API, custom attributes can be referenced by using the fully qualified name. The schema URI is urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.scimName, where scimName is the SCIM name of the custom schema attribute that was created with the POST /Schema/attributes API.

customAttributes

object

name

string

required

The SCIM name of the custom attribute. The SCIM name for a custom schema attribute is defined for the tenant by using the POST /Schema/attributes API.

values

array of strings

required

The values of the custom attribute. Maximum length is 1000 characters.

values*

linkedAccounts

array of objects

The linked accounts for the user.

linkedAccounts

object

externalId

string

required

The ID of a user's external account The maximum length, in combination with realm, is 239 characters.

realm

string

required

The realm name of the user's external account The maximum length, in combination with externalId, is 239 characters.

lastLogin

string

Indicates the time of the last login for the current user entry. Value is a date and time of the form yyyy-mm-ddThh:mm:ssZ.

lastLoginType

string

Indicates the login type used for the last login for the current user entry.

lastLoginRealm

string

Indicates the realm used for the last login for the current user entry.

lastMFA

array of objects

The last MFAs for the user.

lastMFA

object

type

string

required

The type of MFA

value

string

required

The value for this type of MFA

accountExpires

string

The expiration date of the account. The value is a date and time of the form yyyy-mm-ddThh:mm:ssZ. For example, an account expiration of 2021-04-01T16:00:00Z, expires on year 2021, April 1 at 16 hundred hours GMT. When an account is expired, the account's active flag is set to false to prevent login.The process that checks for expired accounts runs every 15 minutes at the top of the hour in GMT+0 time.

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

object

department

string

Identifies the name of the department. Maximum length is 128 characters.

employeeNumber

string

A string identifier, typically numeric or alphanumeric, that is assigned to a person. Typically the number is based on the order of hire. Maximum length is 128 characters.

manager

object

Language

URL


xxxxxxxxxx
1
curl --request POST \
2
     --url https://tenant_url/v2.0/Users \
3
     --header 'accept: application/scim+json' \
4
     --header 'content-type: application/scim+json' \
5
     --header 'usershouldnotneedtoresetpassword: false'

Choose an example:

application/scim+json

201Created.

400The request was incorrect.

403Forbidden.

409The user exists.

500An internal server error occurred.