Access tokens

Tokens are the only credential Git and the API accept in normal use.

Scope

Scope	Meaning
ALL_REPO	Every repository you own, including repos created later
SELECTED_REPO	Only the repository ids you list. repository_ids is required

Grants

Canonical list: Grants.

Grant	What it allows
ALL	Everything below
GIT_HTTP_READ	git clone / fetch
GIT_HTTP_WRITE	git push (read is added if missing)
API_REPOS_READ	List and get repositories
API_REPOS_WRITE	Create and delete repositories (read is added if missing)
API_COMMITS_READ	List branches and commits; fetch files and trees
API_WEBHOOKS	Webhook CRUD, ping, deliveries
API_STORAGE	BYO buckets, verify, error log, oidc-setup
API_OIDC_TRUST	OIDC trust-rule CRUD and setup payload

Reading /v1/account/usage needs a valid token, not a special grant. List and get repositories need API_REPOS_READ. Write includes read, so API_REPOS_WRITE or ALL also works.

Minting and listing tokens via API is stricter: the calling token must have grant ALL and scope ALL_REPO.

Note

The website token form exposes Git, repositories (read or write), commits, webhooks, storage, and OIDC toggles, plus Grant All Permissions. Choose Readonly on Repositories for a token or OIDC rule that can only list and get. Choose Read and write to also create and delete.

Create

Web UI

Open Access tokens. For a laptop or agent, keep Grant All Permissions checked.

amendable-cli

amendable token create \
  --name ci \
  --scope ALL_REPO \
  --grants GIT_HTTP_READ,GIT_HTTP_WRITE,API_REPOS_WRITE

The secret prints once.

Listing tokens:

amendable token list

That list call itself needs ALL + ALL_REPO on the calling token.

curl

List your repositories and copy the id for each repository the token should access:

curl -sS https://api.amendable.io/v1/repositories \
  -H "Authorization: Bearer $AMENDABLE_TOKEN"

{
  "repositories": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "username": "alice",
      "name": "project",
      "active": true,
      "storage_source": "platform"
    }
  ]
}

Pass those ids as repository_ids when you create a SELECTED_REPO token:

curl -sS -X POST https://api.amendable.io/v1/access-tokens \
  -H "Authorization: Bearer $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "selected-git",
    "scope": "SELECTED_REPO",
    "grants": ["GIT_HTTP_READ", "GIT_HTTP_WRITE"],
    "repository_ids": ["11111111-1111-1111-1111-111111111111"]
  }'

Limits

Plan	Token ceiling
Free	20
Pro	100

OIDC-exchanged tokens are short-lived (15 minutes) and do not replace this cap the same way a dashboard token does. See OIDC for machines.

Rotate

There is no regenerate endpoint. Create a new token, switch Git remotes and CI secrets, then delete the old id:

amendable token delete 11111111-1111-1111-1111-111111111111

The secret is never returned on GET after create.