---
updatedAt: 2026-05-21T14:47:46.000Z
---
# Authenticate a user name and password.
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'.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"version": "1.0.0",
"description": "Users & Groups",
"title": "Users & Groups"
},
"servers": [
{
"url": "https://{tenanturl}",
"variables": {
"tenanturl": {
"default": "{tenant_url}",
"description": "URL of your IBM Security Verify tenant"
}
}
}
],
"tags": [
{
"name": "Users Management Version 2.0",
"description": ""
}
],
"paths": {
"/v2.0/Users/authentication": {
"post": {
"tags": [
"Users Management Version 2.0"
],
"summary": "Authenticate a user name and password.",
"description": "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.
\nThe 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'.",
"operationId": "authenticateUser",
"parameters": [
{
"name": "method",
"in": "query",
"description": "Method to use for authentication. Valid value is \"compare\". If not present \"bind\" is used.",
"schema": {
"type": "string"
}
},
{
"name": "returnUserRecord",
"in": "query",
"description": "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.",
"schema": {
"type": "string"
}
},
{
"name": "themeId",
"in": "query",
"description": "The identifier of the theme that you want to apply.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "The body for the authentication operation.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/AuthenticateUserV2"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The operation was successful.",
"content": {
"application/scim+json": {
"schema": {
"$ref": "#/components/schemas/AuthenticateUserResponseV2"
}
}
}
},
"400": {
"description": "The request was incorrect.",
"content": {
"application/scim+json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationExternalErrorMessage"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/scim+json": {
"schema": {
"$ref": "#/components/schemas/ExternalErrorMessage1"
}
}
}
},
"409": {
"description": "A conflict exists.",
"content": {
"application/scim+json": {
"schema": {
"$ref": "#/components/schemas/ExternalErrorMessage1"
}
}
}
},
"500": {
"description": "An internal server error occurred.",
"content": {
"application/scim+json": {
"schema": {
"$ref": "#/components/schemas/ExternalErrorMessage1"
}
}
}
}
},
"x-category": "Users & Groups",
"x-publicAPI": "true",
"x-codegen-request-body-name": "body"
}
}
},
"components": {
"schemas": {
"Notifications": {
"type": "object",
"properties": {
"notifyType": {
"type": "string",
"description": "The value that indicates the type of notification that is sent to the user. If not provided, the default value is EMAIL.",
"enum": [
"EMAIL",
"NONE"
]
},
"notifyPassword": {
"type": "boolean",
"description": "Indicates whether the user's password is included in the notification that is sent to the user. If the attribute is not provided, the behavior defaults to true. This attribute does not apply if the notifyType attribute is set to NONE."
},
"notifyManager": {
"type": "boolean",
"description": "Indicates whether the notification should be sent to the user's manager (if one is set) when a user's password is set or modified. If the attribute is not provided, the behavior defaults to false. This attribute does not apply if the notifyType attribute is set to NONE."
}
}
},
"AuthenticationExternalErrorMessage": {
"required": [
"schemas",
"status"
],
"type": "object",
"properties": {
"schemas": {
"type": "array",
"description": "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 schema \"urn:ietf:params:scim:api:messages:2.0:Error\" is the URI as required by the SCIM specification.",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"description": "The HTTP status code expressed as a JSON string."
},
"detail": {
"type": "string",
"description": "A detailed human-readable message."
},
"scimType": {
"type": "string",
"description": "A SCIM detail error keyword. For an authentication error, the possible return values are: INVALID_CREDS: The user name and/or password is not valid. PWD_EXPIRED: The user's password is expired. ACCOUNT_LOCKED: The user's account is locked. LOCKED_PWD_FAILURES: The user's account is locked because of too many password failures. USER_NOT_ACTIVE: The user is not active. PWD_IN_DICTIONARY: The password is present in the per-tenant bad password dictionary. PWD_IN_GLOBAL_DICTIONARY: The password is present in the Global bad password dicationary. AUTHFAIL_UNKNOWN: The system cannot determine authentication failure."
}
}
},
"AuthenticateUserResponseV2": {
"required": [
"id",
"schemas"
],
"type": "object",
"properties": {
"schemas": {
"type": "array",
"description": "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 schema \"urn:ietf:params:scim:schemas:core:2.0:User\" is returned in the response.",
"items": {
"type": "string"
}
},
"id": {
"type": "string",
"description": "The unique identifier for the resource as defined by the service. This attribute is read-only and is sent by the service. Any value that is specified for this attribute in the JSON POST or PUT request payload is ignored."
}
}
},
"AuthenticateUserV2": {
"required": [
"password",
"schemas",
"userName"
],
"type": "object",
"properties": {
"schemas": {
"type": "array",
"description": "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.",
"items": {
"type": "string"
}
},
"userName": {
"type": "string",
"description": "The user's name."
},
"password": {
"type": "string",
"description": "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": {
"$ref": "#/components/schemas/Notifications"
}
}
},
"ExternalErrorMessage1": {
"required": [
"schemas",
"status"
],
"type": "object",
"properties": {
"schemas": {
"type": "array",
"description": "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 schema \"urn:ietf:params:scim:api:messages:2.0:Error\" is the URI as required by the SCIM specification.",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"description": "The HTTP status code expressed as a JSON string."
},
"detail": {
"type": "string",
"description": "A detailed human-readable message."
}
}
}
}
},
"x-original-swagger-version": "2.0",
"x-explorer-enabled": false
}
```