Workspace Identity

​

How it works

1. The agent requests a token and names the service it is for, the audience. Replicas does not allowlist audiences: any printable ASCII string without spaces, up to 255 characters, works, and replicas:workspace is used when none is given.
2. Replicas signs an RS256 JWT that identifies the organization, environment, workspace, and creator. It is valid for 15 minutes.
3. The service verifies the signature with the issuer’s public keys, checks that the audience is its own, and applies its trust policy to the claims.

​

AWS

Assume arn:aws:iam::123456789012:role/replicas in us-east-1 using workspace identity, then run aws sts get-caller-identity.

aws configure set credential_process \
  'replicas identity aws-credentials --role-arn arn:aws:iam::123456789012:role/replicas --region us-east-1' \
  --profile replicas

1. Allow sts:SetSourceIdentity in the role’s trust policy. AWS rejects the exchange for a role without it. The Null condition makes the source identity required, so exchanges without it fail. Replicas sets the value server-side, so agents can omit it but not change it. The example uses the Replicas Cloud issuer; dedicated and self-hosted deployments replace all three api.replicas.dev references (the provider ARN and both condition keys) with their configured issuer host.
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/api.replicas.dev" },
         "Action": ["sts:AssumeRoleWithWebIdentity", "sts:SetSourceIdentity"],
         "Condition": {
           "StringEquals": { "api.replicas.dev:aud": "sts.amazonaws.com" },
           "StringLike": { "api.replicas.dev:sub": "org:<organization_id>:env:*:workspace:*" },
           "Null": { "sts:SourceIdentity": "false" }
         }
       }
     ]
   }
   
2. Add --source-identity to the command. The token then carries the workspace ID in its https://aws.amazon.com/source_identity claim.
   aws configure set credential_process \
     'replicas identity aws-credentials --role-arn arn:aws:iam::123456789012:role/replicas --region us-east-1 --source-identity' \
     --profile replicas
   

​

Google Cloud

Authenticate gcloud through Workload Identity provider projects/123456789/locations/global/workloadIdentityPools/replicas/providers/replicas using workspace identity, then run gcloud auth print-access-token.

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

​

MCP servers

{
  "url": "https://mcp.example.com",
  "headers": {},
  "auth": { "type": "workspace_identity", "audience": "https://mcp.example.com" }
}

​

Your own APIs

Call https://api.example.com/deploys with a workspace identity token for audience https://api.example.com and show me the response.

replicas identity token --audience https://api.example.com
replicas identity exec --audience https://api.example.com -- sh -c 'curl -H "Authorization: Bearer $REPLICAS_WORKSPACE_TOKEN" https://api.example.com/deploys'

curl -s -X POST http://127.0.0.1:17323/token -d '{"audience":"https://api.example.com"}'

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

​

Token claims

​

Security properties

• No long-lived credentials. Tokens last 15 minutes and are minted when requested. Workspaces cache one per audience in memory while it has at least 5 minutes left and do not persist it as a credential. The AWS helper briefly writes the token to a protected temporary file for the STS exchange and deletes it afterwards, then caches the resulting AWS credentials in a user-only file under ~/.replicas/aws-credentials until shortly before they expire.
• Scoped access. Each token is valid for one audience, and trust policies scope by organization, environment, workspace, or creator.
• Auditable identity. Every token names the organization, environment, and workspace. When a person created the workspace, it also names them, so downstream logs can attribute actions to both.
• Bounded by the workspace. Replicas stops issuing tokens when a workspace sleeps, is archived or deleted, when its creator loses access to the environment, or when plan or feature access goes away. An issued token stays valid until exp; there is no revocation.
• Rate limited. Up to 120 mints per workspace per minute.