Help Center/Identity and Access Management/API Reference/API/Federated Identity Authentication Management/Token/Obtaining a Scoped Token

Updated on 2025-12-27 GMT+08:00

Obtaining a Scoped Token

Function

This API is used to obtain a scoped token through federated identity authentication.

For better experience, you are advised not to obtain a scoped token. Instead, use this API to obtain an unscoped token and then use it in your call of Obtaining Temporary Access Keys and Security Tokens of a Federated User to obtain the temporary access keys and security token for accessing cloud services.

This API can be called using both the global endpoint and region-specific endpoints.

Authorization Information

You do not need to obtain permissions to call this API.

URI

POST /v3/auth/tokens

Request Parameters

**Table 1** Parameters in the request header
Parameter	Mandatory	Type	Description
Content-Type	No	String	Fill application/json;charset=utf8 in this field.

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

**Table 3** auth
Parameter	Mandatory	Type	Description
identity	Yes	Object	Authentication parameters.
scope	Yes	Object	Application scope of the token. Value options: project and domain.

**Table 4** auth.identity
Parameter	Mandatory	Type	Description
methods	Yes	Array of strings	Authentication method. The value of this parameter is token.
token	Yes	Object	Unscoped token information.

**Table 5** auth.identity.token
Parameter	Mandatory	Type	Description
id	Yes	String	Unscoped token ID.

**Table 6** auth.scope
Parameter	Mandatory	Type	Description
domain	No	Object	If this parameter is set to domain, the token can be used to access resources in all projects under the account of a specified ID or name.
project	No	Object	If this parameter is set to project, the token can only be used to access resources in the project of a specified ID or name.

**Table 7** auth.scope.domain
Parameter	Mandatory	Type	Description
id	No	String	Account ID. Either id or name must be specified.
name	No	String	Account name. Either id or name must be specified.

**Table 8** auth.scope.project
Parameter	Mandatory	Type	Description
domain	No	Object	Account information about the project. This parameter is mandatory if the name parameter is set.
id	No	String	Project ID. Either id or name must be specified.
name	No	String	Project name. Either id or name must be specified.

**Table 9** auth.scope.project.domain
Parameter	Mandatory	Type	Description
id	No	String	Account ID. Either id or name must be specified.
name	No	String	Account name. Either id or name must be specified.

Response Parameters

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

**Table 11** Parameters in the response body
Parameter	Type	Description
token	Object	Details of the scoped token.

**Table 12** token
Parameter	Type	Description
methods	Array of strings	Method for obtaining a token.
expires_at	String	Time when the token will expire. NOTE: The value is a UTC time in the YYYY-MM-DDTHH:mm:ss.ssssssZ format, for example, 2023-06-28T08:56:33.710000Z. For details about the date and timestamp formats, see ISO-8601.
catalog	Array of objects	Catalog 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.
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.
issued_at	String	Time when the token was issued. NOTE: The value is a UTC time in the YYYY-MM-DDTHH:mm:ss.ssssssZ format, for example, 2023-06-28T08:56:33.710000Z. For details about the date and timestamp formats, see ISO-8601.

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

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

**Table 15** token.domain
Parameter	Type	Description
name	String	Account name.
id	String	Account ID.

**Table 16** token.project
Parameter	Type	Description
name	String	Project name.
id	String	Project ID.
domain	Object	Account information about the project.

**Table 17** token.project.domain
Parameter	Type	Description
name	String	Account name.
id	String	Account ID.

**Table 18** 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 19** token.user
Parameter	Type	Description
domain	Object	Information about the account used to create the IAM user.
OS-FEDERATION	Object	Federated identity authentication information.
id	String	User ID.
name	String	Username.
password_expires_at	String	Password expiration time. If this parameter is not specified, the password will never expire. NOTE: The value is a UTC time in the YYYY-MM-DDTHH:mm:ss.ssssssZ format, for example, 2023-06-28T08:56:33.710000Z. For details about the date and timestamp formats, see ISO-8601.

**Table 20** token.user.domain
Parameter	Type	Description
name	String	Account name.
id	String	Account ID.

**Table 21** token.user.OS-FEDERATION
Parameter	Type	Description
groups	Array of objects	User group information.
identity_provider	Object	Identity provider information.
protocol	Object	Protocol information.

**Table 22** token.user.OS-FEDERATION.groups
Parameter	Type	Description
id	String	User group ID.
name	String	User group name.

**Table 23** token.user.OS-FEDERATION.identity_provider
Parameter	Type	Description
id	String	Identity provider ID.

**Table 24** token.user.OS-FEDERATION.protocol
Parameter	Type	Description
id	String	Protocol ID.

Example Request

Request for obtaining a scoped token

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

{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "MIIatAYJKoZIhvcNAQcCoIIapTCCGqECAQExDTALB..."
            }
        },
        "scope": {
            "domain": {
                "id": "063bb260a480cecc0f36c0086bb6c..."
            }
        }
    }
}

Example Response

Status code: 201

The request is successful.

Parameters in the response header
X-Subject-Token:MIIatAYJKoZIhvcNAQcCoIIapTCCGqECAQExDTALB...

Parameters in the response body
{
    "token": {
        "expires_at": "2020-02-13T14:21:34.042000Z",
        "methods": [
            "token"
        ],
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "d2983f677ce14f1e81cbb6a9345a107a",
                        "interface": "public",
                        "region": "*",
                        "region_id": "*",
                        "url": "https://iam.eu-west-101.myhuaweicloud.com/v3"
                    }
                ],
                "id": "fd631b3426cb40f0919091d5861d8fea",
                "name": "keystone",
                "type": "identity"
            }
        ],
        "domain": {
            "id": "06aa2260a480cecc0f36c0086bb6cfe0",
            "name": "IAMDomain"
        },
        "roles": [
            {
                "id": "0",
                "name": "te_admin"
            },
            {
                "id": "0",
                "name": "secu_admin"
            }
        ],
        "issued_at": "2020-02-12T14:21:34.042000Z",
        "user": {
            "OS-FEDERATION": {
                "groups": [
                    {
                        "id": "06aa2260bb00cecc3f3ac0084a74038f",
                        "name": "admin"
                    }
                ],
                "identity_provider": {
                    "id": "ACME"
                },
                "protocol": {
                    "id": "saml"
                }
            },
            "domain": {
                "id": "06aa2260a480cecc0f36c0086bb6cfe0",
                "name": "IAMDomain"
            },
            "id": "LdQTDSC7zmJVIic3yaCbLBXDxPAdDxLg",
            "name": "FederationUser",
            "password_expires_at": ""
        }
    }
}

Status Codes

Status Codes	Description
201	The request is successful.
400	Invalid parameters.
401	Authentication failed.
403	Access denied.
404	The requested resource cannot be found.
500	Internal server error.
503	Service unavailable.

Error Codes

None

Parent topic:Token

Previous topic: Obtaining an Unscoped Token (IdP Initiated)

Next topic: Obtaining a Token with an OpenID Connect ID Token

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.