OIDC for machines

CI and agents should not sit on a long-lived Amendable token. Trust their OIDC identity, then exchange it for a 15-minute access token.

Note

This is not BYO S3 OIDC. That other flow is Amendable assuming your AWS role. Different issuer, different audience. See Bring your own S3.

1. Read the setup payload

Needs API_OIDC_TRUST (or ALL) and scope ALL_REPO.

curl -sS https://api.amendable.io/v1/oidc-trust-rules/setup \
  -H "access-token: $AMENDABLE_TOKEN"

You get:

• audience: amendable:<your-user-uuid>
• token_url: https://api.amendable.io/v1/oidc/token
• presets for GitHub Actions and GitLab CI
• a GitHub Actions snippet

Always copy audience from this payload. Do not invent it.

2. Create a trust rule

GitHub Actions

Issuer: https://token.actions.githubusercontent.com

Subject examples:

• One repo, one branch: repo:ORG/REPO:ref:refs/heads/main
• Any ref in a repo: repo:ORG/REPO:* is a documentation example. Prefer the exact sub GitHub puts in the token (repo:ORG/REPO:environment:prod, and so on).

curl -sS -X POST https://api.amendable.io/v1/oidc-trust-rules \
  -H "access-token: $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "gha-main",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "amendable:YOUR_USER_UUID",
    "subject": "repo:YOUR_ORG/YOUR_REPO:ref:refs/heads/main",
    "scope": "ALL_REPO",
    "grants": ["GIT_HTTP_READ", "GIT_HTTP_WRITE", "API_REPOS_WRITE"]
  }'

The GitHub workflow must request that audience:

permissions:
  id-token: write
  contents: read

Then mint an ID token with audience=amendable:<user-uuid> and POST it to /v1/oidc/token. A full workflow is in examples/github-actions/amendable-git.yml.

GitLab CI

Issuer: https://gitlab.com (or your GitLab host if that is what appears in iss)

Subject example:

project_path:GROUP/PROJECT:ref_type:branch:ref:main

Set id_tokens in .gitlab-ci.yml with aud equal to amendable:<user-uuid>, then:

curl -sS -X POST https://api.amendable.io/v1/oidc/token \
  -H "Content-Type: application/json" \
  -d "{\"id_token\": \"$GITLAB_OIDC_TOKEN\"}"

amendable-cli

amendable oidc-exchange --id-token "$ID_TOKEN"

Prints the short-lived Amendable token. Pipe it into AMENDABLE_TOKEN for the rest of the job. The CLI does not persist exchanged tokens unless you write them yourself.

Optional claim_matchers is a map of claim name to exact string match, for extra claims beyond sub.

3. Exchange

POST /v1/oidc/token
Content-Type: application/json

{"id_token": "<jwt>"}

No access-token header. Rate limited.

201/200 body:

{
  "token": "short-lived-access-token",
  "token_type": "access-token",
  "expires_at": "2026-08-23T01:30:00+00:00"
}

Use token as Git HTTPS password and as the access-token header until expires_at.

HTTP 401 with Invalid ID token covers a lot of failures (wrong iss, aud, sub, signature, or no matching rule). Check the trust rule, then the token claims.

Limits

Free accounts: 1 trust rule. Pro: 10. Disable or delete rules you are not using.

Blocked issuers and audiences

You cannot point a trust rule at Amendable’s own BYO issuer (oidc.amendable.io or stage.oidc.amendable.io) or at audience amendable-byo-storage. Those belong to the storage federation path only.