> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Identity

> Give each workspace a short-lived, audience-scoped token your services can verify instead of a stored API key.

Replicas signs a short-lived RS256 JWT for every eligible workspace and renews it
before it expires. Your services verify the token with the issuer's public keys, so a
[workspace](/features/workspaces/overview) can call them without holding a long-lived secret.

<Note>
  Workspace identity (OIDC) is **feature-flagged and disabled by default**. It requires
  a paid Team or Enterprise plan and Replicas to enable the `workspace_identity`
  feature flag for your organization. This includes MCP authentication and the AWS/GCP
  credential helpers. Contact Replicas to request access before following this guide.
</Note>

## Register audiences

Audiences are configured per [environment](/features/environments). Each one names
a service the workspace may present a token to, and the workspace receives a
separate token per audience.

* An environment registers at most 8 audiences, and one of them can be the default.
* Audiences follow environment inheritance: Global first, then the source or
  repository-bound team environment when the workspace runs in a personal one,
  then the environment itself. A more specific entry masks its parent, including
  when it disables the audience.
* `replicas:workspace` is reserved. It is always minted and is the default when no
  enabled default is registered.

Manage them from **Workspace identity** in the environment, or through the
[API](/features/api): `GET /v1/environments/{id}/workload-identity` lists the issuer,
discovery URLs, and registered audiences, and the `workload-audiences` endpoints create,
update, and delete them. Managing audiences requires environment Write; agents running
inside a workspace cannot change them.

## Use the token in a workspace

Every eligible workspace has these variables set:

| Variable                             | Contents                                                         |
| ------------------------------------ | ---------------------------------------------------------------- |
| `REPLICAS_WORKSPACE_TOKEN`           | Token for the default audience at the time the process started   |
| `REPLICAS_WORKSPACE_TOKEN_FILE`      | Path to the token bundle (`~/.replicas/credentials/tokens.json`) |
| `REPLICAS_WORKSPACE_TOKEN_AUDIENCE`  | Default audience for this environment                            |
| `REPLICAS_WORKSPACE_IDENTITY_ISSUER` | Issuer to verify tokens against                                  |

Tokens last 15 minutes, so a value captured into a long-running process goes stale.
Read the bundle file or use the [CLI](/features/cli#workspace-identity) whenever a
current token is needed. `identity exec` sets the variable for the command it runs, so
keep the reference single-quoted and let the command expand it:

```bash theme={null}
replicas identity token
replicas identity token --audience https://mcp.example.com
replicas identity exec -- sh -c 'curl -H "Authorization: Bearer $REPLICAS_WORKSPACE_TOKEN" https://api.example.com'
```

A loopback helper on `127.0.0.1:17323` can attach the token for clients with static
configuration. Request `/identity/<base64url audience>/<base64url target URL>` and it
forwards to the target with the current token in `Authorization`, dropping any
credentials the client sent. It answers `503` until a token is available.

## Authenticate an MCP server

An `http` or `sse` [environment MCP](/features/environments#mcps) can present the
workspace token instead of a stored header by adding `auth` to its config:

```json theme={null}
{
  "url": "https://mcp.example.com",
  "headers": {},
  "auth": { "type": "workspace_identity", "audience": "https://mcp.example.com" }
}
```

The audience has to resolve to a registered, enabled audience for that environment,
the URL must be HTTPS without query parameters, and no static headers are allowed.

## Authenticate cloud tools

Cloud tools use the same refreshed token bundle through their standard credential
helpers. They exchange the workspace token for cloud credentials and call the
provider directly. The MCP loopback proxy is not involved.

### AWS

An AWS administrator first creates an
[IAM OIDC provider and role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
that trust your Replicas issuer. Restrict the role's trust policy to your organization
with a `sub` condition such as `org:<organization_id>:workspace:*`, check the audience,
and grant the role the required AWS permissions. Register `sts.amazonaws.com` as an
audience in Replicas and the IAM OIDC provider.

With the AWS CLI installed, configure a named profile in the workspace or its
[start hook](/features/environments#start-hooks):

```bash theme={null}
aws configure set credential_process \
  'replicas identity aws-credentials --role-arn arn:aws:iam::123456789012:role/replicas --region us-east-1' \
  --profile replicas

aws sts get-caller-identity --profile replicas
```

AWS CLI and SDKs supporting
[`credential_process`](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html)
invoke the helper when they need credentials. It reads the current token, calls
`AssumeRoleWithWebIdentity`, and returns temporary credentials with their expiry.
Use `AWS_PROFILE=replicas` for SDKs, and remove old AWS key variables if they take
precedence. Cloud credential lifetimes are separate from the workspace token's
15-minute lifetime.

### Google Cloud

An administrator first configures
[Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers)
to trust your Replicas issuer, maps `google.subject=assertion.sub`, restricts access
with `assertion.organization_id == '<organization_id>'`, and grants the needed
permissions. Register `https://iam.googleapis.com/<provider-resource-name>` as an
audience in Replicas, matching the audience Google accepts.

With gcloud installed, create a credential configuration in the workspace:

```bash theme={null}
REPLICAS_GCP_PROVIDER='projects/123456789/locations/global/workloadIdentityPools/replicas/providers/replicas'
mkdir -p "$HOME/.replicas/credentials"
gcloud iam workload-identity-pools create-cred-config "$REPLICAS_GCP_PROVIDER" \
  --executable-command="replicas identity token --format gcp --audience https://iam.googleapis.com/$REPLICAS_GCP_PROVIDER" \
  --output-file="$HOME/.replicas/credentials/gcp.json"

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.replicas/credentials/gcp.json"
export GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1
gcloud auth login --cred-file="$GOOGLE_APPLICATION_CREDENTIALS" --quiet
```

Add `--service-account=<email>` to `create-cred-config` if your IAM setup uses service
account impersonation. Set the two variables for processes using Google client
libraries. The libraries run the helper whenever they need a new workspace token
and handle Google's token exchange. The configuration contains no private key.

## Verify tokens in your service

Fetch the issuer's metadata and keys, then verify offline:

* Discovery: `<issuer>/.well-known/openid-configuration`
* Keys: `<issuer>/.well-known/jwks.json`

| Claim                                               | Value                                              |
| --------------------------------------------------- | -------------------------------------------------- |
| `iss`                                               | Your Replicas issuer                               |
| `sub`                                               | `org:<organization_id>:workspace:<workspace_id>`   |
| `aud`                                               | The single audience the token was minted for       |
| `iat`, `nbf`, `exp`, `jti`                          | Standard timing and replay claims                  |
| `organization_id`, `workspace_id`, `environment_id` | Where the token came from                          |
| `creator_id`                                        | Workspace creator, `null` when Replicas created it |

Verify the RS256 signature against the key matching the token's `kid`, check the
issuer and your own audience exactly, and keep tolerated clock skew at or below 30
seconds. `examples/workspace-identity` in the repository holds a reference verifier
plus a plain HTTP server and an MCP server built on it. Services that support OIDC
federation, such as cloud IAM providers, can trust the discovery URL directly.

## Lifecycle and limits

* Tokens last 15 minutes. The workspace engine renews them roughly every 5 minutes
  while the workspace runs, so the bundle always holds a token with at least 10
  minutes left.
* The bundle is owned by the workspace user and readable only by it.
* Replicas stops issuing tokens when a workspace sleeps, is archived or deleted, when
  its creator loses access to the environment, or when the plan or feature access
  goes away. A resumed workspace receives a fresh bundle on start.
* There is no revocation of an issued token: your service accepts it until `exp`.
  Keep the 15-minute lifetime in mind when deciding what a token may do.