Updated on 2024-04-15 GMT+08:00

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.

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.

    Example:

    "totp": {
            "user": {
              "id": "b95b78b67fa045b38104c12fb...",
              "passcode": "******"
    • user.id: User ID, which can be obtained on the My Credentials page.
    • passcode: Virtual MFA device 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": {
    					"id": "dfsafdfsaf....",
    					"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.