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 → Tokens (/settings/api-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 → Tokens; admins can list/revoke any user’s tokens with the governance.admin capability. Revocation is immediate.

Connect an AI agent (MCP)

The same PAT also unlocks the MCP tenant server at POST /api/mcp — a Model Context Protocol endpoint that lets an AI agent (Claude Code or any MCP client) set up your cloud connections conversationally: fetch the exact read-only grant commands for your organization, run them with your own cloud CLI, create the connection, and watch the first sync.

claude mcp add --transport http leancosts \
  https://app.leancosts.com/api/mcp \
  --header "Authorization: Bearer leancosts_pat_xxxxxxxx…"

Then ask: “Using leancosts, connect my AWS payer account.” For least privilege, mint the PAT scoped to costs.connections.manage.

Note

The MCP tools are secretless by design: they never accept a client secret, access key, or service-account key. AWS connects via a cross-account role, GCP via workload identity, and Azure via a device-code sign-in — so no long-lived cloud credential ever appears in the conversation.

Discovering endpoints

The OpenAPI document describes the method + path for every endpoint, grouped by first path segment (/costs/* → tag costs, etc.). Use the Scalar reference UI (/api/docs) to browse and try them in-browser.