Files

weihongmin1 46d24ba358 IAM API 0401 Version

Reviewed-by: Belejkanic, Lukas <lukas.belejkanic@t-systems.com>
Co-authored-by: weihongmin1 <weihongmin1@huawei.com>
Co-committed-by: weihongmin1 <weihongmin1@huawei.com>

2026-01-14 14:13:49 +00:00

79 KiB

Raw Blame History

Obtaining a User Token Through Password Authentication and Virtual MFA

Function

This API is used to obtain an IAM user token using the username, password, and virtual MFA device. 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. The token obtained using this API can be used to authenticate API calls to IAM and other cloud services.

URI

POST /v3/auth/tokens

**Table 1** Query parameters
Parameter	Mandatory	Type	Description
nocatalog	No	String	If this parameter is set, no catalog information will be displayed in the response. Any non-empty string for this parameter will be interpreted as true and indicates that no catalog information will be displayed.

Request

**Table 2** Parameters in the request header
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Set this field to application/json;charset=utf8.

**Table 3** Parameters in the request body
Parameter	Mandatory	Type	Description
auth	Yes	Object	Authentication information.

**Table 4** auth
Parameter	Mandatory	Type	Description
identity	Yes	Object	Authentication parameters.
scope	Yes	Object	Application scope of the token. Value options: project and domain. NOTE: If the scope is set to domain, the token applies to global services. If the scope is set to project, the token applies to project-level services. If the scope is set to both project and domain, the project is used and you get a token for project-level services. If the scope is left blank, you get a token for global services. You are advised to specify this parameter.

**Table 5** auth.identity
Parameter	Mandatory	Type	Description
methods	Yes	Array of strings	Authentication method. The options are as follows: password totp
password	Yes	Object	IAM user password authentication information. NOTE: 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	Yes	Object	Authentication information. This parameter is mandatory only if you have enabled virtual MFA-based login protection. You can specify either user.id or user.name. CAUTION: 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.

**Table 6** auth.identity.password
Parameter	Mandatory	Type	Description
user	Yes	Object	Information about the IAM user who is requesting to obtain a token.

**Table 7** auth.identity.password.user
Parameter	Mandatory	Type	Description
domain	Yes	Object	Information about the account used to create the IAM user.
name	Yes	String	IAM username.
password	Yes	String	Password of the IAM user. NOTE: To obtain a token successfully, ensure that the password you provide is correct. A third-party system user cannot directly obtain a token by using the username and password used for identity federation. Go to the cloud platform login page, click Forgot Password, and reset the password.

**Table 8** auth.identity.password.user.domain
Parameter	Mandatory	Type	Description
name	Yes	String	Name of the account used to create the IAM user.

**Table 9** auth.identity.totp
Parameter	Mandatory	Type	Description
user	Yes	Object	IAM user information. Login protection has been enabled for the IAM user, and a virtual MFA device is used for identity authentication.

**Table 10** auth.identity.totp.user
Parameter	Mandatory	Type	Description
id	Yes	String	ID of the IAM user for whom virtual MFA-based login protection has been enabled.
passcode	Yes	String	MFA verification code, which can be obtained on the MFA App. NOTE: To obtain a token successfully, ensure that the verification code you provide is correct.

**Table 11** auth.scope
Parameter	Mandatory	Type	Description
domain	No	Object	If this parameter 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. domain.id is recommended.
project	No	Object	If this parameter is set to project, the token can be used to access only services (such as ECS) in specific projects. You can specify either id or name.

**Table 12** auth.scope.domain
Parameter	Mandatory	Type	Description
id	No	String	ID of the account used to create the IAM user.
name	No	String	Name of the account used to create the IAM user.

**Table 13** auth.scope.project
Parameter	Mandatory	Type	Description
id	No	String	ID of the project to which the IAM user belongs.
name	No	String	Project name of the account used to create the IAM user.

Example Request

Sample 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

**Table 14** Parameters in the response header
Parameter	Type	Description
X-Subject-Token	String	Signed token.

**Table 15** Parameters in the response body
Parameter	Type	Description
token	Object	Token information.

**Table 16** token
Parameter	Type	Description
catalog	Array of objects	Endpoint information.
domain	Object	Account information about the IAM user who requests for the token. This parameter is returned only when the scope parameter in the request body has been set to domain.
expires_at	String	Expiration date of the token.
issued_at	String	Time when the token was issued.
mfa_authn_at	String	MFA authentication time. This field is displayed only when virtual MFA–based login authentication is enabled.
methods	Array of strings	Method for obtaining the token.
project	Object	Project information about the IAM user who requests for the token. This parameter is returned only when the scope parameter in the request body has been set to project.
roles	Array of objects	Permissions information of the token.
user	Object	Information about the IAM user who requests for the token.

**Table 17** token.catalog
Parameter	Type	Description
endpoints	Array of objects	Endpoint information.
id	String	Service ID.
name	String	Service name.
type	String	Type of the service to which the API belongs.

**Table 18** token.catalog.endpoints
Parameter	Type	Description
id	String	Endpoint ID.
interface	String	Visibility of the API. public indicates that the API is available for public access.
region	String	Region to which the endpoint belongs.
region_id	String	Region ID.
url	String	Endpoint URL.

**Table 19** token.domain
Parameter	Type	Description
name	String	Domain name.
id	String	Domain ID.

**Table 20** token.project
Parameter	Type	Description
domain	Object	Domain information of the project.
id	String	Project ID.
name	String	Project name.

**Table 21** token.project.domain
Parameter	Type	Description
id	String	Domain ID.
name	String	Domain name.

**Table 22** token.roles
Parameter	Type	Description
name	String	Permission name.
id	String	Permission ID. The default value is 0, which does not correspond to any permission.

**Table 23** token.user
Parameter	Type	Description
name	String	IAM username.
id	String	IAM user ID.
password_expires_at	String	Password expiration time. If this parameter is not specified, the password will never expire.
domain	Object	Information about the account used to create the IAM user.

**Table 24** token.user.domain
Parameter	Type	Description
name	String	Name of the account used to create the IAM user.
id	String	ID of the account used to create the IAM user.

Example Response

Example response