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 root user 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 saml:namequalifier saml:sub saml:sub_type	-	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	Definition: security_token field of a temporary security credential. Constraints: When an API is called using a temporary security credential, the HTTP header X-Security-Token must be provided. Range: N/A Default Value: N/A

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
duration_seconds	No	Integer	Definition Validity period (in seconds) of the obtained temporary security credential. Constraints Note that the duration must be less than the maximum session duration set for the agency (which can be obtained on the Agencies page of the IAM console) and cannot exceed 3,600 seconds when the X-Security-Token header is carried. Range The value ranges from 900 to 43200. Default Value The default value is 3600.
external_id	No	String	Definition External ID, which prevents confused deputy issues. Constraints N/A Range The value contains 2 to 1,224 characters, including only letters, digits, and the following special characters: _+=,.@:/- Default Value N/A
policy	No	String	Definition Custom policy, which is used to further restrict the permission scope of temporary security credentials. For details, see Reference. Constraints The permission scope of the temporary security credential obtained in this session cannot exceed the permission scope specified in the custom policy. Range The value contains 2 to 4,096 characters. Default Value N/A
policy_ids	No	Array of strings	Definition List of preset policies. The permission scope of the temporary security credential obtained in this session cannot exceed the permission scope specified in the preset policies. Each element is the ID of a preset policy. The value can contain 1 to 64 characters, including only letters, digits, underscores (_), and hyphens (-). At least one character must be contained. Constraints The array can contain a maximum of 20 elements. Range N/A Default Value N/A
agency_urn	Yes	String	Definition URN of the target agency, which can be obtained on the Agencies page of the IAM console. Constraints N/A Range The value contains a maximum of 1,500 characters. It consists of five segments separated by colons (:). Segment 1 must contain at least 1 character; Segment 2 must contain 0–255 characters; Segment 3 must contain 1–64 characters; Segment 4 must contain 1–64 characters; Segment 5 must contain at least 1 any character. Segments 1–4 may include letters, digits, and special characters (+/=-_); Segment 2 additionally allows asterisks (). Default Value* N/A
agency_session_name	Yes	String	Definition Name of the assumed-agency session. Constraints N/A Range The value contains 2 to 128 characters, including only letters, digits, and the following special characters: _+=,.@- Default Value N/A
serial_number	No	String	Definition Serial number of the MFA device bound to the caller. On the IAM console, choose Users > Security Settings > Multi-Factor Authentication (MFA) to obtain the value. Constraints N/A Range The value can contain 9 to 256 characters. Only letters, digits, and special characters (_+=/:,.@-) are allowed. Default Value N/A
token_code	No	String	Definition Six-digit number of the MFA device bound to the caller. Constraints Only six digits are allowed. Range N/A Default Value N/A
source_identity	No	String	Definition Identity declared by the initial caller in the tracing. Constraints N/A Range The value can contain 2 to 64 characters, including only letters, digits, and the following special characters: _+=,.@- Default Value N/A
tags	No	Array of TagDto objects	Definition List of custom tags. Constraints The array can contain a maximum of 20 elements. Range N/A Default Value N/A
transitive_tag_keys	No	Array of strings	Definition List of tag keys that are continuously transparently transmitted along with the temporary security credential call chain. Constraints The array can contain a maximum of 20 elements. Range N/A Default Value N/A
provided_contexts	No	Array of ProvidedContextDto objects	Definition List of pre-obtained trusted context assertions, in array format. Constraints The array can contain 1 to 5 elements. Range N/A Default Value N/A

**Table 3** TagDto
Parameter	Mandatory	Type	Description
key	Yes	String	Definition Tag key. Constraints N/A Range The value contains 1 to 128 characters. Only letters, digits, spaces, and the following special characters are allowed: _.:=+-@/. The value cannot start with _sys_. Default Value N/A
value	Yes	String	Definition Tag value. Constraints N/A Range The value contains 0 to 255 characters. Only letters, digits, spaces, and the following special characters are allowed: _.:/=+-@ The value can be an empty string but cannot be null. Default Value N/A

**Table 4** ProvidedContextDto
Parameter	Mandatory	Type	Description
context_provider_urn	Yes	String	Definition URN of the provider that generates the trusted context assertion. Constraints The value contains a maximum of 1,500 characters. It consists of five segments separated by colons (:). Segment 1 must contain at least 1 character; Segment 2 must contain 0–255 characters; Segment 3 must contain 1–64 characters; Segment 4 must contain 1–64 characters; Segment 5 must contain at least 1 any character. Segments 1–4 may include letters, digits, and special characters (+/=-_); Segment 2 additionally allows asterisks (). Range* N/A Default Value N/A
context_assertion	Yes	String	Definition Signed and encrypted trusted context assertion. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 5** Response body parameters
Parameter	Type	Description
source_identity	String	Definition: Identity declared by the initial caller in the call chain. Range: N/A
assumed_agency	AssumedAgencyDto object	Definition: Information about an agency session or trust agency session. Range: N/A
credentials	CredentialsDto object	Definition: Generated temporary security credentials. Range: N/A

**Table 6** AssumedAgencyDto
Parameter	Type	Description
urn	String	Definition: URN of an agency session or trust agency session. Range: N/A
id	String	Definition: Unique identifier of an agency session or trust agency session, including the agency ID and agency session name. Range: N/A

**Table 7** CredentialsDto
Parameter	Type	Description
access_key_id	String	Definition: AK of the temporary security credential. Range: N/A
expiration	String	Definition Expiration time of the temporary security credential. The value is a UTC time in ISO 8601 format, for example, 2026-08-21T17:00:01.999Z. Range N/A
secret_access_key	String	Definition: SK of the temporary security credential. Range: N/A
security_token	String	Definition: security_token of the temporary security credential. Range: N/A

Status code: 400

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Definition : Error code. For details, see Error Code. Range: The format is STS5.XXXX, for example, STS5.1001.
error_msg	String	Definition : Error message. For details, see Error Message. Range: N/A.

Status code: 403

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Definition : Error code. For details, see Error Code. Range: The format is STS5.XXXX, for example, STS5.1001.
error_msg	String	Definition : Error message. For details, see Error Message. Range: N/A.
encoded_authorization_message	String	Definition : Encrypted details returned when the authentication fails, which are used to locate authentication problems. The STS5 decryption API can be used for decryption. For details, see API link. Range: N/A.

Status code: 404

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Definition : Error code. For details, see Error Code. Range: The format is STS5.XXXX, for example, STS5.1001.
error_msg	String	Definition : Error message. For details, see Error Message. Range: N/A.

Status code: 500

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Definition : Error code. For details, see Error Code. Range: The format is STS5.XXXX, for example, STS5.1001.
error_msg	String	Definition : Error message. For details, see Error Message. Range: N/A.

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

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