Function

This API is provided for IAM users to obtain a token through username/password and virtual MFA authentication. To use this API, ensure that virtual MFA-based login protection has been enabled for the IAM user.

A token is an access credential issued to a user to bear its identity and permissions. When calling the APIs of IAM or other cloud services, you can use this API to obtain a token for authentication.

The API can be called using both the global endpoint and region-specific endpoints. For IAM endpoints, see Regions and Endpoints.

• Validity period of a token

  The validity period of a token is 24 hours. Cache the token to prevent frequent API calling. 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. However, the following operations will invalidate the existing token:

  • Deleting or disabling the IAM user
  • Changing the IAM user's password or access key
  • The IAM user's permissions are changed due to outstanding payments, OBT application approval, or permission modification.
• Obtaining a token
  • If your HUAWEI CLOUD account has been upgraded to a HUAWEI ID, you cannot obtain a token using the HUAWEI ID. Instead, you can create an IAM user, grant the user required permissions, and obtain a token as the user.
  • If you are a user of a third-party system, you cannot obtain a token by using the username and password that you use for federated identity authentication. Go to the HUAWEI CLOUD login page, click Forgot password, click Reset HUAWEI CLOUD account password, and set a password.
• Related operations
  • To obtain a token with Security Administrator permissions, see How Do I Obtain a Token with Security Administrator Permissions?
  • For details on how to obtain a token using Postman, see How Do I Obtain a User Token Using Postman?

URI

POST /v3/auth/tokens

Request Parameters

Example Request

• Example 1: Request for obtaining a token for IAM user IAMUser (password: IAMPassword; account name: IAMDomain; scope: domain)

  POST https://iam.myhuaweicloud.com/v3/auth/tokens

  {
      "auth": {
          "identity": {
              "methods": [
                  "password",
                  "totp"
              ],
              "password": {
                  "user": {
                      "name": "IAMUser",                            // IAM user name.
                      "password": "IAMPassword",                   // IAM user password.
                      "domain": {
                          "name": "IAMDomain"                      // Name of the account to which the IAM user belongs.
                      }
                  }
              },
              "totp": {
                  "user": {
                      "id": "7116d09f88fa41908676fdd4b039e...",  // IAM user ID.
                      "passcode": "******"                           // Virtual MFA verification code.
                  }
              }
          },
          "scope": {
              "domain": {
                  "name": "IAMDomain"                                 // Name of the account to which the IAM user belongs.
              }
          }
      }
  }

• Example 2: Request for obtaining a token for IAM user IAMUser (password: IAMPassword; account name: IAMDomain; scope: project cn-north-1) without displaying catalog information in the response

  POST https://iam.myhuaweicloud.com/v3/auth/tokens?nocatalog=true

  {
      "auth": {
          "identity": {
              "methods": [
                  "password",
                  "totp"
              ],
              "password": {
                  "user": {
                      "name": "IAMUser",                            // IAM user name.
                      "password": "IAMPassword",                   // IAM user password.
                      "domain": {
                          "name": "IAMDomain"                      // Name of the account to which the IAM user belongs.
                      }
                  }
              },
              "totp": {
                  "user": {
                      "id": "7116d09f88fa41908676fdd4b039e...",  // IAM user ID.
                      "passcode": "******"                           // Virtual MFA verification code.
                  }
              }
          },
          "scope": {
              "project": {
                  "name": "cn-north-1"                                // Project name.
              }
          }
      }
  }

Response Parameters

Example Response

Status code: 201

The request is successful.

• Example 1: Response to the request for obtaining a token for IAM user IAMUser (password: IAMPassword; account name: IAMDomain; scope: domain)

  Parameters in the response header (obtained token)
  X-Subject-Token:MIIatAYJKoZIhvcNAQcCoIIapTCCGqECAQExDTALB...

  Parameters in the response body
  {
      "token": {
          "expires_at": "2020-01-04T09:08:49.965000Z",
          "mfa_authn_at": "2020-01-03T09:08:49.965000Z",
          "methods": [
              "password",
              "totp"
          ],
          "catalog": [
              {
                  "endpoints": [
                      {
                          "id": "33e1cbdd86d34e89a63cf8ad16a5f...",
                          "interface": "public",
                          "region": "*",
                          "region_id": "*",
                          "url": "https://iam.myhuaweicloud.com/v3.0"
                      }
                  ],
                  "id": "100a6a3477f1495286579b819d399...",
                  "name": "iam",
                  "type": "iam"
              },
              {
                  "endpoints": [
                      {
                          "id": "29319cf2052d4e94bcf438b55d143...",
                          "interface": "public",
                          "region": "*",
                          "region_id": "*",
                          "url": "https://bss.myhuaweicloud.com/v1.0"
                      }
                  ],
                  "id": "c6db69fabbd549908adcb861c7e47...",
                  "name": "bssv1",
                  "type": "bssv1"
              }
          ],
          "domain": {
              "id": "d78cbac186b744899480f25bd022f...",
              "name": "IAMDomain"
          },
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "secu_admin"
              },
              {
                  "id": "0",
                  "name": "te_agency"
              }
          ],
          "issued_at": "2020-01-03T09:08:49.965000Z",
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

• Example 2: Response to the request for obtaining a token for IAM user IAMUser (password: IAMPassword; account name: IAMDomain; scope: project cn-north-1) without displaying catalog information in the response

  Parameters in the response header (obtained token)
  X-Subject-Token:MIIatAYJKoZIhvcNAQcCoIIapTCCGqECAQExDTALB...

  Parameters in the response body
  {
      "token": {
          "expires_at": "2020-01-04T09:05:22.701000Z",
          "mfa_authn_at": "2020-01-03T09:05:22.701000Z",
          "methods": [
              "password",
              "totp"
          ],
          "catalog": [],
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "op_gated_OBS_file_protocol"
              },
              {
                  "id": "0",
                  "name": "op_gated_Video_Campus"
              }
          ],
          "project": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "aa2d97d7e62c4b7da3ffdfc11551f...",
              "name": "cn-north-1"
          },
          "issued_at": "2020-01-03T09:05:22.701000Z",
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

Status code: 400

Invalid parameters.

{
    "error": {
        "code": 400,
        "message": "The request body is invalid",
        "title": "Bad Request"
    }
}

Status code: 401

Authentication failed.

• If you are a user of a third-party system, you cannot obtain a token by using the username and password that you use for federated identity authentication. Go to the HUAWEI CLOUD login page, click Forgot password, click Reset HUAWEI CLOUD account password, and set a new password.
• If your HUAWEI CLOUD account has been upgraded to a HUAWEI ID, you cannot obtain a token using the HUAWEI ID. Instead, you can create an IAM user, grant the user required permissions, and obtain a token as the user.

{
    "error": {
        "code": 401,
        "message": "The username or password is wrong.",
        "title": "Unauthorized"
    }
}

Status Codes

Error Codes

None