Authentication

Every automated call uses an access token. Humans sign in to the website with email and password (plus optional MFA). Git and the API do not use the account password.

API

GET /v1/account/usage HTTP/1.1
Host: api.amendable.io
access-token: YOUR_TOKEN

There is no Authorization header. The header name is access-token.

curl

curl -sS https://api.amendable.io/v1/account/usage \
  -H "access-token: $AMENDABLE_TOKEN"

Python

import os
import httpx

r = httpx.get(
    "https://api.amendable.io/v1/account/usage",
    headers={"access-token": os.environ["AMENDABLE_TOKEN"]},
)
r.raise_for_status()
print(r.json())

JavaScript

const res = await fetch("https://api.amendable.io/v1/account/usage", {
  headers: { "access-token": process.env.AMENDABLE_TOKEN },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

amendable-cli

amendable whoami --json

Git HTTPS

https://amendable.io/r/<username>/<repo>.git

HTTP Basic:

• Username: your Amendable username (the token lookup uses the password, so a dummy username can work, but using the real username keeps credential helpers sane)
• Password: the access token

The token needs GIT_HTTP_READ to clone and GIT_HTTP_WRITE to push.

Caution

If Git asks for a password and you type the website password, it may work on some environments and fail on others. Create an access token and use that. The product is built around tokens.

Create a token

Web

https://amendable.io/access-tokens/create

Leave Grant All Permissions on unless you know you want a narrower token.

CLI device grant

amendable login

This calls POST https://api.amendable.io/v1/auth/sessions with your hostname, prints a code, and opens:

https://amendable.io/access-tokens/create?auth_session_id=<uuid>

Confirm the code matches, grant the token, and the CLI polls GET /v1/auth/sessions/{id}/poll?secret_token=... until it receives the secret. Poll returns 202 until you grant.

Those session routes are omitted from the public OpenAPI schema (include_in_schema=False) but they work. If you call create yourself, poll HTTPS https://api.amendable.io/v1/auth/sessions/{id}/poll. Ignore a poll_url field if it is http://.

API (needs an existing admin token)

Creating tokens via API requires the calling token to have grant ALL and scope ALL_REPO.

curl -sS -X POST https://api.amendable.io/v1/access-tokens \
  -H "access-token: $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-readwrite",
    "scope": "ALL_REPO",
    "grants": ["GIT_HTTP_READ", "GIT_HTTP_WRITE", "API_REPOS_WRITE"]
  }'

The secret is in token on this response only.

OIDC exchange (no long-lived token in CI)

Create a trust rule, then:

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

No access-token header on this call. The response is a short-lived token (15 minutes) plus expires_at.

See OIDC for machines.

Environment variables used by the CLI

Variable	Meaning
AMENDABLE_TOKEN	Access token (overrides the config file)
AMENDABLE_API_URL	Default https://api.amendable.io. Staging: https://stage.api.amendable.io
AMENDABLE_APP_URL	Default https://amendable.io. Staging: https://stage.amendable.io
AMENDABLE_USERNAME	Used when you pass a bare repo name
AMENDABLE_CONFIG	Path to the TOML config file

Config file default: ~/.config/amendable/config.toml.