• Identity and Access Management

iam
  1. Help Center
  2. Identity and Access Management
  3. API Reference
  4. Token Management
  5. Obtaining a User Token

Obtaining a User Token

Function Description

This interface is used to obtain a token. A token is generated after the username and password are authenticated. (After virtual MFA device is enabled, a token is generated after the username, password, and verification code are authenticated.)

NOTE:
  • The validity period of a token is 24 hours. If you want to use a token for authentication, cache it to avoid frequently calling the IAM API.
  • This interface provides a lockout mechanism for preventing brute force cracking. Ensure that the username and password are correct when calling this interface. If you enter the username and password incorrectly for a certain number of times (specified by the security administrator), the account will be locked.

URI

URI format

POST /v3/auth/tokens

Request

  • Request header parameter description

    Parameter

    Mandatory

    Type

    Description

    Content-Type

    Yes

    String

    Fill application/json;charset=utf8 in this field.


  • Request body parameter description

    Parameter

    Mandatory

    Type

    Description

    identity

    Yes

    JSON Object

    The value can be methods, password, or totp. For details, see Table 1.

    scope

    No

    JSON Object

    Range in which the token takes effect. This field can be set to domain or project and they cannot be set to the same level.

    Example 1:

    This example indicates that the token is allowed to access only resources of the examplename account.

    "scope": {
          "domain": {
          "name": "examplename"
          }
        }

    name indicates the account name. examplename is used as an example.

    Example 2:

    This example indicates that the token is allowed to access only resources under the project with the ID of 0215ef11e49d4743be23dd97a1561e91 of the account to which the user belongs.

    "scope": {
          "project": {
          "id": "0215ef11e49d4743be23dd97a1561e91"
          }
        }

    Example 3:

    This example indicates that the token is allowed to access only resources under the project named project_example of the account examplename.

        "scope": {
            "domain": {
                "name": "exampledomain",
                "project": {
                    "id": "0215ef11e49d4743be23dd97a1561e91"
                }
            }
        }
    Table 1 Description for the identity format

    Parameter

    Mandatory

    Type

    Description

    methods

    Yes

    String Array

    Enter password in this field. If virtual MFA-based login authentication is enabled, enter ["password","totp"] in this field.

    password

    Yes

    JSON Object

    Example:

    "password": {
    "user": {
    "name": "name",
    "password": "**********",
    "domain": {
    "name": "name"
    }
    }
    }

    domainname: name of an account to which a user belongs.

    username: name of a user.

    password: password used for login.

    totp

    No

    JSON Object

    This parameter is mandatory when virtual MFA-based login authentication is enabled.

    Example:

    "totp": {
    "user": {
    "id": "b95b78b67fa045b38104c12fb2729cd0",
    "passcode": "******"
    }
    }
  • Sample request

    Obtain the token of user exampleuser whose password is ********** and domain name is exampledomain.

    {
      "auth": {
        "identity": {
          "methods": ["password"],
          "password": {
            "user": {
              "name": "exampleuser",
              "password": "**********",
              "domain": {
                "name": "exampledomain"
              }
            }
          }
        },
        "scope": {
          "domain": {
            "name": "exampledomain"
          }
        }
      }
    }

    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": "name",
    "password": "**********",
    "domain": {
    "name": "name"
    
    }
    }
    },
    "totp": {
    "user": {
    "id": "id",
    "passcode": "******"
    }
    }
    },
    "scope": {
    "domain": {
    "name": "name"
    }
    }
    }
    }

Response

  • Response header parameter description

    Parameter

    Mandatory

    Type

    Description

    X-Subject-Token

    Yes

    String

    A signed token.

  • Token format description

    Parameter

    Mandatory

    Type

    Description

    methods

    Yes

    JSON Array

    Method for obtaining a token.

    expires_at

    Yes

    String

    Token expiration time.

    issued_at

    Yes

    String

    Time when a token is generated.

    user

    Yes

    JSON Object

    Example:

    "user": { 
          "name": "username", 
          "id": ""en-us_topic_0057845583__en-us_topic_0026585112_i438354691645">domainname",
             "id": "domainid"
           } 
        }

    username: name of a user.

    "en-us_topic_0057845583__a8fac11b7236847e4ac96ab14ef284ced"> domainname: name of an account to which a user belongs.

    domainid: ID of an account to which a user belongs.

    password_expires_at: password expiration time (UTC time). If the value is null, the password will not expire. This parameter is optional.

    domain

    No

    JSON Object

    The system determines whether to return this field based on the scope specified in a request.

    Example:

    "domain": { 
          "name" : "domainame",     
          "id" : "domainid"}

    domainname: name of an account.

    domainid: ID of an account.

    project

    No

    JSON Object

    The system determines whether to return this field based on the scope specified in a request.

    Example:

    "project": { 
          "name": "projectname", 
          "id": "projectid", 
          "domain": { 
             "name": "domainname",
             "id": "domainid"
           } 
       }

    projectname: name of a project.

    projectid: ID of a project.

    domainname: name of an account to which a project belongs.

    domainid: ID of an account to which a project belongs.

    catalog

    Yes

    JSON Array

    Details of endpoints.

    Example:

    "catalog": [{
        "type": "identity",
        "id": "1331e5cff2a74d76b03da1225910e31d",
        "name": "iam",
        "endpoints": [{
            "url": "www.example.com/v3",
            "region": "*",
            "region_id": "*",
            "interface": "public",
            "id": "089d4a381d574308a703122d3ae738e9"
        }]
    }]

    roles

    Yes

    JSON Object

    Role list.

    Example:

    "roles" : [{ 
         "name" : "role1", 
         "id" : "roleid1" 
         }, { 
         "name" : "role2", 
         "id" : "roleid2" 
         } 
       ] 
  • Sample response
    Information included in the response header:
    X-Subject-Token:MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...
    
    Information included 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" : "default",
          "name" : "exampledomain"
          },
          "id" : "ee4dfb6e5540447cb37419051XXX..",
          "name" : "exampleuser",
          "password_expires_at":"2016-11-06T15:32:17.000000",
        },
        "domain" : {
           "name" : "exampledomain",
           "id" : "default"
        },
        "catalog": [{
            "type": "identity",
            "id": "1331e5cff2a74d76b03da12259XXXX...",
            "name": "iam",
            "endpoints": [{
                "url": "www.example.com/v3",
                "region": "*",
                "region_id": "*",
               "interface": "public",
                 "id": "089d4a381d574308a703122d3aXXXX..."
           }]
        }], 
        "roles" : [{
           "name" : "role1",
           "id" : "roleid1"
           }, {
           "name" : "role2",
           "id" : "roleid2"
           }
      ]
      }
    }

Status Codes

Status Code

Description

201

The request is successful.

400

The server failed to process the request.

401

You must enter a username and password to access the requested page.

403

You are forbidden to access the requested page.

404

The server could not find the requested page.

500

Failed to complete the request because of an internal service error. The format may be incorrect.

503

Failed to complete the request because the service is unavailable.