Use the API with a token

Call the leancosts HTTP API from a script, CI job, or scheduled refresh using a Personal Access Token (PAT) instead of a browser session.

1. Mint a token

In the web app: User menu → Settings → API Tokens (/settings/tokens) → create token. At mint time you can:

• set a TTL (default 90 days, max 365),
• optionally narrow the scopes to a subset of your capabilities (empty = inherit everything you can already do).

The cleartext token — leancosts_pat_<64 hex> — is shown exactly once. Copy it now; only its sha256 is stored server-side. If you lose it, revoke and reissue.

Caution

A PAT inherits your effective capabilities and is pinned to one organization. If you’re later removed from that org, the token stops working (pat_org_revoked). PAT bearers cannot mint new tokens — minting requires a cookie session.

2. Call the API

Send the token as a bearer header:

curl -H "Authorization: Bearer leancosts_pat_xxxxxxxx…" \
  https://app.leancosts.com/api/change-requests

The same gate protects the docs endpoints, so a token also unlocks:

• GET https://app.leancosts.com/api/openapi.json — the OpenAPI 3.1 document (every registered endpoint, method + path).
• GET https://app.leancosts.com/api/docs — the Scalar API reference UI (click Authorize, paste your PAT, and try requests in-browser).

The token’s prefix is intentionally greppable (GitHub/Stripe-style) so a leaked token is easy to spot in CI logs — treat it like a password and prefer a CI secret store.

3. Revoke when done

Revoke your own tokens from Settings → API Tokens; admins can list/revoke any user’s tokens with the governance.admin capability. Revocation is immediate.

Discovering endpoints

The OpenAPI document currently describes method + path for every route (~360 operations), grouped by first path segment (/costs/* → tag costs, etc.). Per-operation request/response schemas are being filled in incrementally.