Personal access tokens #

Personal access tokens (PATs) are long-lived bearer tokens for your own account — the right choice for scripts, CI pipelines, server-to-server integrations and the Microbooks MCP server. No redirects, no refresh logic: create one, store it as a secret, and send it as a bearer token.

From the dashboard (recommended) #

Sign in to microbooks.io and go to Developers → API tokens. Name the token, tick the scopes it needs, and copy the JWT — it is shown exactly once.

Treat PATs like passwords. They are valid for a year by default. Create one token per device or use case, grant only the scopes needed (skip :write for read-only jobs), and revoke tokens you stop using.

Over the API #

Method	Endpoint	Action
`GET`	`/auth/v1/tokens`	List your active tokens (metadata only — never the JWT)
`POST`	`/auth/v1/tokens`	Issue a token
`DELETE`	`/auth/v1/tokens/{id}`	Revoke a token

Request #

curl --request POST 'https://api.microbooks.io/auth/v1/tokens' \
--header 'Authorization: Bearer <bearer_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "ci-pipeline",
    "scopes": ["books:read", "books:write"]
}'

Response #

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "token": {
        "id": "a1b2c3d4e5f6...",
        "name": "ci-pipeline",
        "scopes": ["books:read", "books:write"],
        "created_at": "2026-08-04T12:00:00.000000Z",
        "expires_at": "2027-08-04T12:00:00.000000Z"
    }
}

The access_token is returned only in this response. Requesting scopes your account is not entitled to fails with a validation error.

Using a token #

curl 'https://api.microbooks.io/books/v1/reports/income-statement' \
--header 'Authorization: Bearer <personal access token>'