# What is workload identity?

Workload identity lets code prove what it is with a short-lived signed token, and trade it for cloud access without holding a stored key.

**On Runtime every sandbox can get an OpenID Connect token that names the
sandbox, its organization and its image, free, with no API key.** Your AWS or
Google Cloud account trusts Runtime once, and a sandbox then assumes a role for
as long as its token and the credentials it buys last
([identity tokens](/docs/identity-tokens)).

## Why it matters for AI agents

An agent that deploys, reads a bucket or queries a database needs credentials.
The usual answer is a long-lived key in an environment variable, and a sandbox
running model-written code is the worst place to keep one: a prompt injection
can print it, and a copied key works until someone notices. Google's own
documentation calls service account keys "powerful credentials" that "can
present a security risk if they are not managed correctly".

With workload identity the sandbox holds nothing worth stealing for long. It
asks for a token when it needs one, the cloud checks who signed it and what it
says, and hands back credentials that expire on their own.

## Workload identity in facts

| Fact                  | Value                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------- |
| Token format          | An OpenID Connect ID token, a signed JSON Web Token                                   |
| Required claims       | `iss` (who issued it), `sub` (who it is about), `aud` (who it is for), `exp`, `iat`   |
| AWS exchange          | `AssumeRoleWithWebIdentity`; needs no AWS credentials to call                         |
| AWS session length    | One hour by default; 900 seconds up to the role's maximum, at most 12 hours           |
| Google Cloud exchange | Workload Identity Federation, a federated token traded for a short-lived access token |
| Best-known example    | GitHub Actions, whose tokens are "only valid for a single job"                        |
| Runtime token         | 10 minutes by default, 60 to 3600 seconds on request, RS256, audience required        |
| Runtime subject       | `org:<org-id>:image:<image>:sandbox:<sandbox-id>`                                     |

## How it works on Runtime

Inside a sandbox, ask for a token with the audience of the system that will
check it:

```ts check
import { Sandbox } from "withruntime";

const { token, subject } = await Sandbox.identityToken({ audience: "sts.amazonaws.com" });
console.log(subject, token.length);
```

```python check
from withruntime import Sandbox

token = Sandbox.identity_token("sts.amazonaws.com")
print(len(token))
```

In AWS IAM you add `https://withruntime.com/oidc` as an OpenID Connect provider
and write a role trust policy that matches `sub`. The pattern
`org:<org-id>:*` admits every sandbox of your organization, and
`org:<org-id>:image:api-worker:*` only those made from one image, so no other
Runtime customer can assume the role ([AWS](/docs/identity-tokens#aws)). Your
own API can verify the same token against the published keys at
`https://withruntime.com/oidc/jwks`.

The sandbox's permission to ask for tokens covers only itself, only while it
runs, and ends with its lease. The signing keys never leave Runtime's servers.
Azure is not supported yet, because Entra ID's federated credentials match an
exact subject and every sandbox's subject differs.

## Related

- [Identity tokens](/docs/identity-tokens)
- [Security: identity tokens instead of stored keys](/docs/security#identity-tokens-instead-of-stored-keys)
- [What are least-privilege API keys?](/glossary/least-privilege-api-keys)
- [How to run untrusted code from an LLM safely](/use-cases/run-untrusted-llm-code)
- [How to use identity tokens with AWS](/how-to/use-identity-tokens-with-aws)
- [How to run sandboxes from GitHub Actions](/how-to/run-sandboxes-from-github-actions)

## Sources

Checked 25 September 2026.

- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html): the ID token and its required claims
- [AWS STS: AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html): session length and the call's credential needs
- [Google Cloud: Workload Identity Federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation): service account key risk and the token exchange
- [GitHub: OpenID Connect](https://docs.github.com/en/actions/concepts/security/openid-connect): tokens for a single job

Facts on this page were checked on 25 September 2026.