Obtain a workload access token - Agent Identity - Alibaba Cloud Documentation Center

What is a workload access token?

A workload access token is an opaque token issued by the Agent Identity service for a workload identity after completing inbound authentication for a caller, typically an agent. The agent can then use this token to access Agent Identity APIs, such as requesting an access token from an OAuth credential provider to reach 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

Agent Identity provides three API operations to obtain a workload access token, each designed for a different scenario:

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. Agent Identity validates the JWT's signature, issuer (`iss`), and expiration to confirm the user identity is authentic and valid. This is the recommended method for production environments.	Medium. Agent Identity trusts the `userId` string provided by the caller without additional validation. Security 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 call an API manually. The runtime automatically selects the token acquisition method based on the 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

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")