AssumeRole - API Reference| Alibaba Cloud Documentation Center

Limits

This operation is available only to a RAM user that is allowed to assume a RAM role by using an STS token. If the RAM user is not allowed to assume a RAM role by using an STS token, the following error message is returned:
```
You are not authorized to do this action. You should be authorized by RAM.
```
You can refer to the following information to troubleshoot the error:
- Cause of the error: The policy that is required to assume a RAM role is not attached to the RAM user. To resolve this issue, attach the AliyunSTSAssumeRoleAccess policy or a custom policy to the RAM user. For more information, see Grant permissions to a RAM user and Can I specify the RAM role that a RAM user can assume?.
- Cause of the error: The RAM user that you use is not added to the trust policy of the RAM role. In other words, the RAM user does not have the permissions to assume the RAM role. To resolve this issue, add the RAM user to the Principal element in the trust policy of the RAM role. For more information, see Edit the trust policy of a RAM role.
STS allows each Alibaba Cloud account to send up to 6,000 AssumeRole requests per minute. API requests that are sent by using RAM users and RAM roles that belong to the Alibaba Cloud account are also counted.
If an Alibaba Cloud account sends more than 6,000 AssumeRole requests within a minute, the following error message is returned for the excessive requests:
```
Request was denied due to user flow control.
```

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	AssumeRole	The operation that you want to perform. Set the value to AssumeRole.
RoleArn	String	Yes	acs:ram::123456789012****:role/adminrole	The Alibaba Cloud Resource Name (ARN) of the RAM role. The trusted entity of the RAM role is an Alibaba Cloud account. For more information, see Create a RAM role for a trusted Alibaba Cloud account or CreateRole. Format: `acs:ram::$accountID:role/$roleName`. Note You can view the ARN in the RAM console or by calling operations. For more information about how to view the ARN in the RAM console, see How do I view the ARN of a RAM role?. For more information about how to view the ARN by calling operations, see ListRoles or GetRole.
RoleSessionName	String	Yes	alice	The custom name of the role session. In most cases, this parameter is set to the identity of the user who calls the operation, for example, the username. In ActionTrail logs, you can distinguish the users who assume the same RAM role to perform operations based on the value of the RoleSessionName parameter. This way, you can perform user-specific auditing. The value must be 2 to 64 characters in length and can contain letters, digits, periods (.), at signs (@), hyphens (-), and underscores (_).
Policy	String	No	null	The policy that specifies the permissions of the returned STS token. You can use this parameter to grant the STS token fewer permissions than the permissions granted to the RAM role. If you specify this parameter, the permissions of the returned STS token are the permissions that are included in the value of this parameter and owned by the RAM role. If you do not specify this parameter, the returned STS token has all the permissions of the RAM role. The value must be 1 to 1,024 characters in length.
DurationSeconds	Long	No	3600	The validity period. Unit: seconds. Minimum value: 900. Maximum value: the value of the MaxSessionDuration parameter. Default value: 3600. Note You can call the CreateRole or UpdateRole operation to configure the MaxSessionDuration parameter. For more information, see CreateRole and UpdateRole.

Response parameters


Parameter	Type	Example	Description
RequestId	String	6894B13B-6D71-4EF5-88FA-F32781734A7F	The ID of the request.
Credentials			The access credentials.
└AccessKeyId	String	STS.L4aBSCSJVMuKg5U1****	The AccessKey ID.
└AccessKeySecret	String	wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****	The AccessKey secret.
└SecurityToken	String	********	The STS token.
└Expiration	String	2015-04-09T11:52:19Z	The time when the STS token expires.
AssumedRoleUser			The temporary identity that you use to assume the RAM role.
└Arn	String	acs:ram::123456789012****:role/adminrole/alice	The ARN of the temporary identity that you use to assume the RAM role.
└AssumedRoleId	String	34458433936495****:alice	The ID of the temporary identity that you use to assume the RAM role.

Examples

Sample requests

https://sts.aliyuncs.com/?Action=AssumeRole
&RoleArn=acs:ram::123456789012****:role/adminrole
&RoleSessionName=alice
&DurationSeconds=3600
&Common request parameters

Note For more information about common request parameters, see Common parameters.

Sample success responses

XML format

<AssumeRoleResponse>
    <RequestId>6894B13B-6D71-4EF5-88FA-F32781734A7F</RequestId>
    <AssumedRoleUser>
        <Arn>acs:ram::123456789012****:role/adminrole/alice</arn>
        <AssumedRoleId>34458433936495****:alice</AssumedRoleId>
    </AssumedRoleUser>
    <Credentials>
        <AccessKeyId>STS.L4aBSCSJVMuKg5U1****</AccessKeyId>
        <AccessKeySecret>wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****</AccessKeySecret>
        <SecurityToken>********</SecurityToken>
        <Expiration>2015-04-09T11:52:19Z</Expiration>
    </Credentials>
</AssumeRoleResponse>

JSON format

{
    "Credentials": {
        "AccessKeyId": "STS.L4aBSCSJVMuKg5U1****",
        "AccessKeySecret": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
        "Expiration": "2015-04-09T11:52:19Z",
        "SecurityToken": "********"
    },
    "AssumedRoleUser": {
        "Arn": "acs:ram::123456789012****:role/adminrole/alice",
        "AssumedRoleId":"34458433936495****:alice"
        },
    "RequestId": "6894B13B-6D71-4EF5-88FA-F32781734A7F"
}

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidParameter	The parameter RoleArn is wrongly formed.	The error message returned because the ARN format of the RAM role is invalid.
400	InvalidParameter.RoleArn	The parameter RoleArn is wrongly formed.	The error message returned because the ARN format of the RAM role is invalid.
400	InvalidParameter.RoleSessionName	The parameter RoleSessionName is wrongly formed.	The error message returned because the format of the RoleSessionName parameter is invalid. The value must be 2 to 64 characters in length and can contain letters, digits, periods (.), at signs (@), hyphens (-), and underscores (_).
400	InvalidParameter.DurationSeconds	The Min/Max value of DurationSeconds is 15min/1hr.	The error message returned because the value of the DurationSeconds parameter is invalid. The minimum value is 900, and the maximum value is equal to the value of the MaxSessionDuration parameter.
400	InvalidParameter.PolicyGrammar	The parameter Policy has not passed grammar check.	The error message returned because the syntax of the policy is invalid.
400	InvalidParameter.PolicySize	The size of Policy must be smaller than 1024 bytes.	The error message returned because the length of the specified policy string exceeds the upper limit. The policy string can be up to 1,024 characters in length.
403	NoPermission	You are not authorized to do this action. You should be authorized by RAM.	The error message returned because the STS token does not have the required permissions. For more information about how to fix the error, see FAQ about RAM roles and STS tokens.
404	EntityNotExist.Role	The specified Role not exists.	The error message returned because the specified RAM role does not exist.
500	InternalError	STS Server Internal Error happened.	The error message returned because an internal error occurred in the server.

What to do next

After the STS token is obtained, the RAM user can use the STS token to assume the RAM role and access Alibaba Cloud resources.