Obtaining a Temporary Security Credential Through an Agency or Trust Agency

Function

This API is used to obtain a temporary security credential through an agency or trust agency. The temporary security credential can be used to control access to cloud resources.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the following required identity policy-based permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
sts:agencies:assume	Write	agency *	g:ResourceTag/<tag-key>	-	sts::tagSession sts::setSourceIdentity
sts:agencies:assume	Write	-	sts:ExternalId sts:SourceIdentity sts:TransitiveTagKeys sts:AgencySessionName g:RequestTag/<tag-key> g:TagKeys g:SourceAccount g:SourceUrn	-	sts::tagSession sts::setSourceIdentity

URI

POST /v5/agencies/assume

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Security-Token	No	String	When an API is called using a temporary security credential, the HTTP request header X-Security-Token must be provided. The value is the security_token field of the temporary security credential.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
duration_seconds	No	Integer	Validity period (in seconds) of the obtained temporary security credential. Note that the duration must be less than the maximum session duration set for the agency and cannot exceed 3600 seconds when the X-Security-Token header is carried. Minimum: 900 Maximum: 43200 Default: 3600
external_id	No	String	External ID to prevent confused deputy problem. Minimum: 2 Maximum: 1224
policy	No	String	Custom policy. The permission scope of the temporary security credential obtained in this session cannot exceed the permissions specified in the custom policy. Minimum: 2 Maximum: 2048
policy_ids	No	Array of strings	Predefined policy list. The permission scope of the temporary security credential obtained in this session cannot exceed the permissions specified in the predefined policy. Maximum: 64
agency_urn	Yes	String	URN of a target agency. Maximum: 1500
agency_session_name	Yes	String	Name of the assumed-agency session. Minimum: 2 Maximum: 128
serial_number	No	String	Serial number of the virtual MFA device bound to a caller. Minimum: 9 Maximum: 256
token_code	No	String	6-digit code of the virtual MFA device bound to a caller. Minimum: 6 Maximum: 6
source_identity	No	String	Identity declared by the initial caller in the call chain. Minimum: 2 Maximum: 64
tags	No	Array of TagDto objects	List of custom tags.
transitive_tag_keys	No	Array of strings	Tag key list that is transparently transmitted along with the temporary security credential in the call chain.

**Table 3** TagDto
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. Minimum: 1 Maximum: 128
value	Yes	String	Tag value, which can be an empty string but cannot be null. Minimum: 0 Maximum: 255

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
source_identity	String	Identity declared by the initial caller in the call chain. Minimum: 2 Maximum: 64
assumed_agency	AssumedAgencyDto object	Target agency information.
credentials	CredentialsDto object	Generated temporary security credential.

**Table 5** AssumedAgencyDto
Parameter	Type	Description
urn	String	URN of a target agency. Maximum: 1500
id	String	Unique ID of a target agency, including the agency ID and agency session name. Maximum: 256

**Table 6** CredentialsDto
Parameter	Type	Description
access_key_id	String	AK of the temporary security credential. Minimum: 20 Maximum: 20
expiration	String	Expiration time of the temporary security credential.
secret_access_key	String	SK of the temporary security credential. Minimum: 40 Maximum: 40
security_token	String	security_token of the temporary security credential.

Status code: 400

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 403

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
encoded_authorization_message	String	Encrypted authentication failure information, which can be decrypted using the STS5 decryption API.

Status code: 404

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 500

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Requests

Obtaining a temporary security credential through agency Y0yfCQYJGO of account 27680d67da6b47eb82d00a1a118be145

POST https://{endpoint}/v5/agencies/assume

{
  "duration_seconds" : 3600,
  "agency_urn" : "iam::27680d67da6b47eb82d00a1a118be145:agency:Y0yfCQYJGO",
  "agency_session_name" : "session1"
}

Example Responses

Status code: 200

Successful

{
  "assumed_agency" : {
    "urn" : "sts::{account_id}::assumed-agency:{agency_name}/{agency_session_name}",
    "id" : "{agency_id}:{agency_session_name}"
  },
  "credentials" : {
    "access_key_id" : "HSTANO...XBS55JLJ3",
    "secret_access_key" : "EoWCQrr...SCcw4Whkt2aXKWAr",
    "security_token" : "hQpjbi1XXXXXX...XXXXXKbhBbA0TQ==",
    "expiration" : "2022-09-07T03:27:51.158Z"
  }
}