Obtain a workload access token-Agent Identity(AgentIdentity)-阿里云帮助中心

What is a workload access token?

A workload access token is an opaque token. The Agent Identity service issues a workload access token for a workload identity after completing inbound authentication for a caller (typically an agent). An agent can use this workload access token to access the Agent Identity service, for example, to request an access token from an OAuth credential provider to access external resources.

A workload access token has the following characteristics:

It can only be used to access the APIs of the Agent Identity service.
The token contains information about both the workload identity and the end-user identity of the caller.
After receiving an end-user request, an agent runtime such as Model Studio, AI Studio, or LangStudio automatically obtains this token by calling the Agent Identity service and injects it into the agent execution environment.

Token acquisition methods

The Agent Identity service provides three API operations to obtain a workload access token for different business scenarios:

Comparison dimension	`GetWorkloadAccessToken`	`GetWorkloadAccessTokenForJWT`	`GetWorkloadAccessTokenForUserId`
Core scenario	No user interaction; intended for automated processes.	Involves user interaction where users sign in through an identity provider (IdP).	User interaction is involved.
User identity	No user identity is present.	Validated through a standard JSON Web Token (JWT).	Declared through a custom user ID string.
Security	High. The token represents only the agent itself, ensuring security and control.	Highest. The Agent Identity service validates the JWT's signature, issuer (`iss`), and expiration to verify that the user identity is authentic and valid. This is the best practice for production environments.	Medium. The Agent Identity service fully trusts the `userId` string provided by the caller without performing additional validation. The security of this method depends on the caller's own authentication and session management.
Use case	An agent runs in the background to perform automated tasks that do not involve specific user data, such as data synchronization or report generation.	After a user signs in to an application through an OIDC-compatible IdP, such as Alibaba Cloud, DingTalk, or a self-hosted corporate IdP, the application backend exchanges the user's JWT for a workload access token. The agent then uses this token to perform operations that require strong identity verification.	The application uses a custom user system that cannot issue standard JWTs but can generate a stable and unique ID for each signed-in user. This method is suitable for quickly integrating various custom identity systems or for simulating users during development and testing.
Potential risks/disadvantages	Cannot be used to obtain credentials tied to a user's personal account.	This method has the strictest requirement for the caller: the application must be able to obtain the user's JWT.	The caller is solely responsible for ensuring the uniqueness, correctness, and security of the `userId`. If a `userId` is guessed or stolen, it could lead to a privilege escalation risk.

If an agent is deployed in an agent runtime, such as Model Studio, AI Studio, or LangStudio, you do not need to manually call an API to obtain a workload access token. The agent runtime automatically selects the method to obtain the token based on the provided user context:

If the user context contains a user token, the runtime calls the GetWorkloadAccessTokenForJWT operation.
If the user context does not contain a user token but includes a user ID, the runtime calls the GetWorkloadAccessTokenForUserId operation.
If the user context contains neither a user token nor a user ID, the runtime calls the GetWorkloadAccessToken operation.

Note

When you call any of the GetWorkloadAccessToken* operations, you must provide the name of a configured workload identity. The caller must also complete inbound authentication. For more information, see Inbound authentication methods.
Before calling these operations, you must grant the corresponding permission policy to the caller in RAM. The required permissions are as follows:
- GetWorkloadAccessTokenForJWT operation: agentidentitydata:GetWorkloadAccessTokenForJWT
- GetWorkloadAccessTokenForUserId operation: agentidentitydata:GetWorkloadAccessTokenForUserId
- GetWorkloadAccessToken operation: agentidentitydata:GetWorkloadAccessToken

Manual token acquisition

You can use the Agent Identity SDK to obtain a workload access token. The following Python code provides an example:

from agent_identity_python_sdk import IdentityClient

# Initialize the client for the China (Beijing) region.
identity_client = IdentityClient(region_id="cn-beijing")

# Get a workload access token by using a user token (JWT).
workload_access_token = identity_client.get_workload_access_token(
  workload_name="your-workload-identity-name",
  user_token="your-user-token"
)

# Get a workload access token by using a user ID.
workload_access_token = identity_client.get_workload_access_token(
  workload_name="your-workload-identity-name",
  user_id="your-user-id"
)

# Get a workload access token without user context.
workload_access_token = identity_client.get_workload_access_token(workload_name="your-workload-identity-name")