Obtaining a User Token¶
Function¶
This API is used to obtain a token through username/password authentication. A token is a system object encapsulating the identity and permissions of a user. When calling the APIs of IAM or other cloud services, you can use this API to obtain a token for authentication.
Note
Tokens are valid for 24 hours and you can cache them to reduce the number of API calls needed. Ensure that the token is valid while you use it. Using a token that will soon expire may cause API calling failures. Obtaining a new token does not affect the validity of the existing token. The following operations will invalidate the existing token. After these operations are performed, obtain a new token.
Changing the password or access key of your account or an IAM user: The token of your account or the user is invalidated.
Deleting or disabling an IAM user: The token of the user is invalidated.
Changing the permissions of an IAM user: The token of the user is invalidated. For example, when the user is added to or removed from a user group, or when permissions of the group which the user belongs to are modified.
URI¶
POST /v3/auth/tokens
Request Parameters¶
Parameters in the request header
Parameter
Mandatory
Type
Description
Content-Type
Yes
String
Fill application/json;charset=utf8 in this field.
Parameters in the request body
Parameter
Mandatory
Type
Description
identity
Yes
JSON object
Authentication parameters, including: methods and password.
"identity": { "methods": ["password"], "password": {
methods
Yes
String Array
Authentication method. The value of this field is password. If virtual MFA-based login authentication is enabled, the value of this field is ["password","totp"].
password
Yes
JSON object
Authentication information. Example:
"password": { "user": { "name": "user A", "password": "**********", "domain": { "name": "domain A"
user.name: Name of the user that wants to obtain the token. Obtain the username on the My Credentials page.
password: Login password of the user.
domain.name: Name of the domain that created the user. Obtain the domain name on the My Credentials page.
totp
No
JSON object
Authentication information. This parameter is mandatory only when virtual MFA-based login authentication is enabled.
You can specify either user.id or user.name.
Example 1:
"totp": { "user": { "id": "b95b78b67fa045b38104c12fb...", "passcode": "******"
user.id: User ID, which can be obtained on the My Credentials page.
passcode: MFA verification code, which can be obtained on the MFA App.
Example 2:
"totp": { "user": { "name": "user A", "passcode": "******"
user.name: Name of the user that wants to obtain the token.
passcode: MFA verification code, which can be obtained on the MFA App.
scope
No
JSON object
Usage scope of the token. The value can be project or domain.
Example 1: If this field is set to project, the token can be used to access only services in specific projects, such as ECS. You can specify either id or name.
"scope": { "project": { "id": "0b95b78b67fa045b38104c12fb..." } }
Example 2: If this field is set to domain, the token can be used to access global services, such as OBS. Global services are not subject to any projects or regions. You can specify either id or name.
"scope": { "domain": { "name": " domain A" } }
Example request
The following is a sample request for obtaining a token for user A. The login password of the user is ********** and the domain name is domain A. The scope of the token is domain.
{ "auth": { "identity": { "methods": ["password"], "password": { "user": { "name": "user A", "password": "**********", "domain": { "name": "domain A" } } } }, "scope": { "domain": { "name": "domain A" } } } }
The following is a sample request for obtaining a token when virtual MFA-based login authentication is enabled.
{ "auth": { "identity": { "methods": ["password", "totp"], "password": { "user": { "name": "user A", "password": "********", "domain": { "name": "domain A" } } }, "totp" : { "user": { "name": "user A", "passcode": "******" } } }, "scope": { "domain": { "name": "domain A" } } } }
Response Parameters¶
Parameters in the response header
Parameter
Mandatory
Type
Description
X-Subject-Token
Yes
String
Obtained token.
Token format description
Parameter
Mandatory
Type
Description
methods
Yes
Json Array
Method for obtaining a token.
expires_at
Yes
String
Expiration date of the token.
issued_at
Yes
String
Time when the token was issued.
mfa_authn_at
No
String
MFA authentication time. This field is displayed only when virtual MFA-based login authentication is enabled.
user
Yes
JSON object
Example:
"user": { "name": "user A", "id": "b95b78b67fa045b38104...", "password_expires_at":"2016-11-06T15:32:17.000000", "domain": { "name": "domain A", "id": "fdec73ffea524aa1b373e40..." } }
user.name: Name of the user that wants to obtain the token.
user.id: ID of the user.
domain.name: Name of the domain that created the user.
domain.id: ID of the domain.
password_expires_at: Coordinated Universal Time (UTC) that the password will expire. null indicates that the password will not expire.
domain
No
JSON object
This parameter is returned only when the scope parameter in the request body has been set to domain.
Example:
"domain": { "name" : "domain A" "id" : "fdec73ffea524aa1b373e40..."
domain.name: Name of the domain that created the user.
domain.id: ID of the domain.
project
No
JSON object
This parameter is returned only when the scope parameter in the request body has been set to project.
Example:
"project": { "name": "project A", "id": "34c77f3eaf84c00aaf54...", "domain": { "name": "domain A", "id": "fdec73ffea524aa1b373e40..." } }
project.name: Name of a project.
project.id: ID of the project.
domain.name: Domain name of the project.
domain.id: Domain ID of the project.
catalog
Yes
Json Array
Endpoint information.
Example:
"catalog": [{ "type": "identity", "id": "1331e5cff2a74d76b03da1225910e...", "name": "iam", "endpoints": [{ "url": "https://sample.domain.com/v3", "region": "*", "region_id": "*", "interface": "public", "id": "089d4a381d574308a703122d3ae73..." }] }]
type: Type of the service which the API belongs to.
id: ID of the service.
name: Name of the service.
endpoints: Endpoints that can be used to call the API.
url: URL used to call the API.
region: Region in which the service can be accessed.
region_id: ID of the region.
interface: Type of the API. The value public means that the API is open for access.
id: ID of the API.
roles
Yes
JSON object
Permissions information of the token.
Example:
"roles" : [{ "name" : "role1", "id" : "roleid1" }, { "name" : "role2", "id" : "roleid2" } ]
Example response
The following is a sample request for obtaining a token for user A. The login password of the user is ********** and the domain name is domain A. The scope of the token is domain.
Token information stored in the response header: X-Subject-Token:MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX... Token information stored in the response body: { "token" : { "methods" : ["password"], "expires_at" : "2015-11-09T01:42:57.527363Z", "issued_at" : "2015-11-09T00:42:57.527404Z", "user" : { "domain" : { "id" : "ded485def148s4e7d2se41d5se...", "name" : "domain A" }, "id" : "ee4dfb6e5540447cb37419051...", "name" : "user A", "password_expires_at":"2016-11-06T15:32:17.000000", }, "domain" : { "name" : "domain A", "id" : "dod4ed5e8d4e8d2e8e8d5d2d..." }, "catalog": [{ "type": "identity", "id": "1331e5cff2a74d76b03da12259...", "name": "iam", "endpoints": [{ "url": "https://sample.domain.com/v3", "region": "*", "region_id": "*", "interface": "public", "id": "089d4a381d574308a703122d3a..." }] }], "roles" : [{ "name" : "role1", "id" : "roleid1" }, { "name" : "role2", "id" : "roleid2" } ] } }
The following is a sample request for obtaining a token when virtual MFA-based login authentication is enabled.
Token information stored in the response header: X-Subject-Token:MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX... Token information stored in the response body: { "token": { "expires_at": "2020-09-05T06:50:44.390000Z", "mfa_authn_at": "2020-09-04T06:50:44.390000Z", "issued_at": "2020-09-04T06:50:44.390000Z", "methods": [ "password", "totp" ], "catalog": [ { "endpoints": [ { "id": "33e1cbdd86d34e89a63cf8ad16a5f...", "interface": "public", "region": "*", "region_id": "*", "url": "https://sample.domain.com/v3.0" } ], "id": "100a6a3477f1495286579b819d399...", "name": "iam", "type": "iam" }, ], "domain": { "id": "e6505630658e49649784759cdf251...", "name": "domain A" }, "roles": [ { "name" : "role1", "id" : "roleid1" },{ "name" : "role1", "id" : "roleid1" } ], "user": { "domain": { "id": "e6505630658e49649784759cdf251...", "name": "domain A" }, "id": "092ac6365a0025b11f76c01e90100...", "name": "user A", "password_expires_at": "" } } }
Status Codes¶
Status Code | Description |
|---|---|
201 | The request is successful. |
400 | The server failed to process the request. |
401 | Authentication failed. |
403 | Access denied. |
404 | The requested resource cannot be found. |
500 | Internal server error. The format may be incorrect. |
503 | Service unavailable. |