文档首页/ 统一身份认证服务 IAM_统一身份认证服务（新版）/ API参考/ API/ STS/ 临时安全凭证/ 通过委托或者信任委托获取临时安全凭证 - AssumeAgency
更新时间：2026-05-27 GMT+08:00
查看PDF
分享

通过委托或者信任委托获取临时安全凭证 - AssumeAgency

功能介绍

通过委托或者信任委托获取临时安全凭证，临时安全凭证可用于对云资源发起访问。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见权限和授权项。

授权项

访问级别

资源类型（*为必须）

条件键

别名

依赖的授权项

sts:agencies:assume

Write

agency *

g:ResourceTag/<tag-key>

-
  • sts::tagSession
  • sts::setSourceIdentity

-

  • sts:ExternalId

  • sts:SourceIdentity

  • sts:TransitiveTagKeys

  • sts:AgencySessionName

  • g:RequestTag/<tag-key>

  • g:TagKeys

  • g:SourceAccount

  • g:SourceUrn

URI

POST /v5/agencies/assume

请求参数

表1 请求Header参数

参数

是否必选

参数类型

描述

X-Security-Token

否

String

参数解释：

临时安全凭证的security_token字段。

约束限制：

通过临时安全凭证调用接口时，需要提供“X-Security-Token”Http头。

取值范围：

不涉及。

默认取值：

不涉及。
表2 请求Body参数

参数

是否必选

参数类型

描述

duration_seconds

否

Integer

参数解释：

获得的临时安全凭证的有效时间（单位秒）。

约束限制：

请注意，该时间需要小于委托本身设置的最大会话持续时间，同时在携带X-Security-Token的Header头时该时间不能超过3600秒。

取值范围：

取值范围为[900-43200]。

默认取值：

默认值为3600。

external_id

否

String

参数解释：

外部ID，防止混淆代理人问题。

约束限制：

长度范围为[2-1224]。

取值范围：

不涉及。

默认取值：

不涉及。

policy

否

String

参数解释：

自定义策略，参考链接。

约束限制：

本次会话获得的临时安全凭证的权限范围不会超过该自定义策略指定的权限。

长度范围为[2-2048]。

取值范围：

不涉及。

默认取值：

不涉及。

policy_ids

否

Array of strings

参数解释：

预置策略列表，限制本次会话获得的临时安全凭证的权限范围不会超过该预置策略指定的权限。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

agency_urn

是

String

参数解释：

目标委托的URN。

约束限制：

长度范围为[0,1500]。

取值范围：

不涉及。

默认取值：

不涉及。

agency_session_name

是

String

参数解释：

委托会话的会话名。

约束限制：

长度范围为[2,128]。

取值范围：

不涉及。

默认取值：

不涉及。

serial_number

否

String

参数解释：

调用者绑定的MFA设备的序列号。

约束限制：

长度范围为[9,256]。

取值范围：

不涉及。

默认取值：

不涉及。

token_code

否

String

参数解释：

调用者绑定的MFA设备上的6位数字码。

约束限制：

长度范围为[6,6]。

取值范围：

不涉及。

默认取值：

不涉及。

source_identity

否

String

参数解释：

调用链里最初调用者所声明的身份。

约束限制：

长度范围为[2,64]。

取值范围：

不涉及。

默认取值：

不涉及。

tags

否

Array of TagDto objects

参数解释：

自定义标签列表。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

transitive_tag_keys

否

Array of strings

参数解释：

随着临时安全凭证调用链持续透传的标签键列表。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表3 TagDto

参数

是否必选

参数类型

描述

key

是

String

参数解释：

标签键。

约束限制：

长度范围为[1,128]。

取值范围：

不涉及。

默认取值：

不涉及。

value

是

String

参数解释：

标签值。

约束限制：

长度范围为[0,255]。

取值范围：

取值可以为空字符串，不可以为null。

默认取值：

不涉及。

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

source_identity

String

参数解释：

调用链里最初调用者所声明的身份。

取值范围：

不涉及。

assumed_agency

AssumedAgencyDto object

参数解释：

目标委托信息。

取值范围：

不涉及。

credentials

CredentialsDto object

参数解释：

生成的临时安全凭证。

取值范围：

不涉及。
表5 AssumedAgencyDto

参数

参数类型

描述

urn

String

参数解释：

目标委托的URN。

取值范围：

不涉及。

id

String

参数解释：

目标委托的唯一标识，包含了委托ID和委托会话名称信息。

取值范围：

不涉及。
表6 CredentialsDto

参数

参数类型

描述

access_key_id

String

参数解释：

临时安全凭证的AK。

取值范围：

不涉及。

expiration

String

参数解释：

临时安全凭证的失效时间。

取值范围：

不涉及。

secret_access_key

String

参数解释：

临时安全凭证的SK。

取值范围：

不涉及。

security_token

String

参数解释：

临时安全凭证的security_token。

取值范围：

不涉及。

状态码：400

表7 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码，请参见错误码。

取值范围：

格式为STS5.XXXX，例如 STS5.1001。

error_msg

String

参数解释：

错误信息，请参见错误信息。

取值范围：

不涉及。

状态码：403

表8 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码， 请参见错误码。

取值范围：

格式为STS5.XXXX， 例如 STS5.1001。

error_msg

String

参数解释：

错误信息， 请参见错误信息。

取值范围：

不涉及。

encoded_authorization_message

String

参数解释：

认证失败时返回的加密详细信息，用于定位认证问题。 可以通过STS5解密接口进行解密，接口链接。

取值范围：

不涉及。

状态码：404

表9 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码，请参见错误码。

取值范围：

格式为STS5.XXXX，例如 STS5.1001。

error_msg

String

参数解释：

错误信息，请参见错误信息。

取值范围：

不涉及。

状态码：500

表10 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码，请参见错误码。

取值范围：

格式为STS5.XXXX，例如 STS5.1001。

error_msg

String

参数解释：

错误信息，请参见错误信息。

取值范围：

不涉及。

请求示例

通过账号27680d67da6b47eb82d00a1a118be145下的委托Y0yfCQYJGO获取临时安全凭证。

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

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

响应示例

状态码：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"
  }
}

状态码

状态码

描述

200

请求成功。

400

请求体异常。

403

没有操作权限。

404

未找到对应资源。

500

服务端异常。

错误码

请参见错误码。

父主题： 临时安全凭证

相关文档