Obtaining a User Token Through Password Authentication

Function

This API is used to obtain a user token using the username and password. A token is an access credential issued to an IAM 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 user token for authentication. However, you are advised to call APIs through AK/SK-based authentication to prevent API calling failures caused by invalid cached tokens.

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

Quick links

Obtaining a token as an IAM user

Checking whether the current account is a HUAWEI ID or a Huawei Cloud account

Obtaining a token using a HUAWEI ID

Obtaining a token using a Huawei Cloud account

Obtaining a token as a third-party system user

Validity period of a token

FAQs about obtaining a token

Related operations

• Obtaining a token as an IAM user

  See Request Parameters.

• Checking whether the current account is a HUAWEI ID or a Huawei Cloud account

  Check whether your account has been upgraded from Huawei Cloud account to HUAWEI ID by referring to How Do I Know What Account I Am Logged In With?

• Obtaining a token using a HUAWEI ID

  You cannot directly use a HUAWEI ID to obtain a token. You need to create an IAM user, assign permissions to the user, and use the user to obtain a token.

• Obtaining a token using a Huawei Cloud account

  See Request Parameters.

• Obtaining a token as a third-party system 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. Instead, you should go to the Huawei Cloud login page, click Forgot password, click Reset Huawei Cloud account password, and set a password.

• 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.
  • The token will become invalid within 30 minutes if any of the following occurs:
    • The IAM user is deleted or disabled.
    • The IAM user's password or access key is changed.
    • The IAM user's permissions are changed (due to outstanding payments, OBT application approval, or permission modification).
  • If The token must be updated is returned when a token is used to call a cloud service API, the token has expired. You need to obtain a new token.
• FAQs about obtaining a token

  Incorrect user name or password: Check whether the entered user name and password are correct. If the username and password are correct but the error persists, check whether you have used a HUAWEI ID to obtain a token. A HUAWEI ID cannot be directly used to obtain a token. You need to create an IAM user, grant permissions to the user, and use the user to obtain a token.

  No API access permissions: Before calling an API, ensure that you have enabled programmatic access.

  Whether a token can be tampered with: Token signature verification ensures that a token has not been tampered with by validating its signature.

• Related operations
  • If login protection has been enabled and the verification method has been set to virtual MFA device, obtain a token as an IAM user by following the instructions provided in Obtaining a User Token Through Password and Virtual MFA Authentication.
  • 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?

Debugging

You can debug this API in API Explorer.

URI

POST /v3/auth/tokens

Request Parameters

Example Request

• Request for obtaining a token for IAM user IAMUser (password: IAMPassword; account name: IAMDomain; scope: project ap-southeast-1) without displaying catalog information in the response. You can obtain the IAM username and account name on the My Credentials page of the console. For details, see Obtaining Account, IAM User, Group, Project, Region, and Agency Information.

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

  {
      "auth": {
          "identity": {
              "methods": [
                  "password"
              ],
              "password": {
                  "user": {
                      "domain": {
                          "name": "IAMDomain"        // Name of the account used to create the IAM user.
                      },
                      "name": "IAMUser",             // IAM username.
                      "password": "IAMPassword"      // IAM user password.
                  }
              }
          },
          "scope": {
              "project": {
                  "name": "ap-southeast-1"               //Project name
              }
          }
      }
  }

• Request for obtaining a token for IAM user IAMUser (password: IAMPassword; account name: IAMDomain; scope: domain) You can obtain the IAM username and account name on the My Credentials page of the console. For details, see Obtaining Account, IAM User, Group, Project, Region, and Agency Information.

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

  {
      "auth": {
          "identity": {
              "methods": [
                  "password"
              ],
              "password": {
                  "user": {
                      "domain": {
                          "name": "IAMDomain"        // Name of the account used to create the IAM user.
                      },
                      "name": "IAMUser",             // IAM username.
                      "password": "IAMPassword"      // IAM user password.
                  }
              }
          },
          "scope": {
              "domain": {
                  "name": "IAMDomain"        // Name of the account used to create the IAM user.
              }
          }
      }
  }

Response Parameters

Example Response

Status code: 201

The request is successful.

• Response to the request for obtaining a token for IAM user IAMUser (password: IAMPassword; account name: IAMDomain; scope: project ap-southeast-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": {
          "catalog": [],
          "expires_at": "2020-01-04T09:05:22.701000Z",
          "issued_at": "2020-01-03T09:05:22.701000Z",
          "methods": [
              "password"
          ],
          "project": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "aa2d97d7e62c4b7da3ffdfc11551f...",
              "name": "ap-southeast-1"
          },
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "op_gated_Video_Campus"
              }
          ],
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

• 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": {
          "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.sample.domain.com/v1.0"
                      }
                  ],
                  "id": "c6db69fabbd549908adcb861c7e47...",
                  "name": "bssv1",
                  "type": "bssv1"
              }
          ],
          "domain": {
              "id": "d78cbac186b744899480f25bd022f...",
              "name": "IAMDomain"
          },
          "expires_at": "2020-01-04T09:08:49.965000Z",
          "issued_at": "2020-01-03T09:08:49.965000Z",
          "methods": [
              "password"
          ],
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "secu_admin"
              },
              {
                  "id": "0",
                  "name": "te_agency"
              }
          ],
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

Status code: 400

Invalid parameters. Check whether the request body complies with the JSON syntax.

{
    "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