Workspace Identity

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 can call them without holding a long-lived secret.

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.

Register audiences

Audiences are configured per environment. 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: 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 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:

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 can present the workspace token instead of a stored header by adding auth to its config:

{
  "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 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:

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 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 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:

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.

Get started

Workspaces

Coding agents

Integrations

Build and automate

Apps

Admin

Updates

Register audiences

Use the token in a workspace

Authenticate an MCP server

Authenticate cloud tools

AWS

Google Cloud

Verify tokens in your service

Lifecycle and limits

​Register audiences

​Use the token in a workspace

​Authenticate an MCP server

​Authenticate cloud tools

​AWS

​Google Cloud

​Verify tokens in your service

​Lifecycle and limits

Register audiences

Use the token in a workspace

Authenticate an MCP server

Authenticate cloud tools

AWS

Google Cloud

Verify tokens in your service

Lifecycle and limits