Authenticate a user name and password.

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

Entitlement required: manageUserGroups (Manage users and groups), or manageAllUserGroups (Synchronize users and groups), or manageUserStandardGroups (Manage users and standard groups), or authn (Authenticate yourself), or authnAnyUser (Authenticate any user), 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 email template for branding is at "notifications/user_management/login/{locale}/user_account_locked_email.xml". Pass in the themeId query parameter to brand the email template for notifications.

* Versions of this API before September 2021 returned a scimType of LOCKED_PWD_FAILURES when a user was locked out because of invalid credentials. The API now returns a scimType of INVALID_CREDS and a notification is sent to the user, stating that the account was locked. Use the urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification element in the POST body to determine the type of notification.

If custom password intelligence warning is enabled and a password is provided that is listed in it, the 200 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 200 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

method

string

Method to use for authentication. Valid value is "compare". If not present "bind" is used.

returnUserRecord

string

Set the value to true to return the complete user record if the user is authenticated. If not present or present and not true, only the user's idattribute is returned if the user is authenticated.

themeId

string

The identifier of the theme that you want to apply.

Body Params

The body for the authentication operation.

schemas

array of strings

required

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

schemas*

userName

string

required

The user's name.

password

string

required

The user's password.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.

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

object

Responses

Language

URL


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

Choose an example:

application/scim+json

200The operation was successful.

400The request was incorrect.

403Forbidden.

409A conflict exists.

500An internal server error occurred.