Getting started

Authentication & access tokens

Every programmatic request to Excaliwow authenticates with a Personal Access Token. Mint one in your account settings, pick a scope, and use it from the API, the CLI, or the MCP server.

Create a token

Tokens live in your account settings on the hosted product. To create one:

Sign in at excaliwow.com.
Open Settings, then Developer / API tokens.
Create a Personal Access Token and choose its scope (see below).
Copy the token immediately. It is shown once, so store it somewhere safe before you leave the page.

Scopes

A token holds exactly one scope. Pick the narrowest scope that does the job: a token that only ever reads diagrams should be read.

Scope	Description
`read`	Grants every read endpoint: identity (`GET /api/v1/me`), list diagrams, get a diagram, render, and list folders.
`read-write`	Everything `read` grants, plus every mutating action: create a diagram or folder, rename, move, delete, merge an edit, and toggle a public link. A `read-write` token also satisfies any endpoint that only requires `read`.

Calling a write endpoint with a read token returns 403 insufficient_scope. Mint a read-write token if you need to create or change diagrams.

Authenticate a request

Send the token in the standard bearer header on every request:

Header

Authorization: Bearer <token>

The quickest way to confirm a token works is to call the identity endpoint, which echoes back the calling user and scope:

Verify a token

curl https://excaliwow.com/api/v1/me \
  -H "Authorization: Bearer <token>"

# 200 OK
# { "id": "<userId>", "email": "[email protected]", "scope": "read-write" }

See the REST API reference for the full set of endpoints.

Use it with the CLI and MCP

Both the CLI and the MCP server read your token from the EXCALIWOW_TOKEN environment variable:

Environment variable

export EXCALIWOW_TOKEN="<token>"

The CLI can also store a login so you do not have to set the variable each time. It validates the token before saving it:

CLI login

excaliwow auth login          # paste the token at the masked prompt

# non-interactively, or in CI:
excaliwow auth login --token "$EXCALIWOW_TOKEN"

When both are present, EXCALIWOW_TOKEN takes precedence over the stored login. See the CLI guide and the MCP server guide for setup details.

Verified email required

Your account email must be verified before a token can do anything beyond the identity check. A request from an unverified account returns 403 email_unverified. The one exception is GET /api/v1/me, which still answers so you can confirm a token is valid. Verify your email from your account, then retry.

Rate limits

Requests are rate limited per user across two independent buckets, one for reads and one for writes:

Bucket	Applies to	Description
`Read requests`	GET	120 requests per minute (default).
`Write requests`	POST / PUT / PATCH / DELETE	30 requests per minute (default).
`Window`	Both	60 seconds. The two buckets are counted independently, per user.

Going over a cap returns 429 with a Retry-After header (in seconds) indicating when the window resets. Wait that long, then retry.

Errors

Every failure returns JSON with the same shape. The error field is a stable machine code; the optional message is a human-readable sentence and is omitted entirely when there is no extra detail.

Error envelope

{
  "error": "<machine_code>",
  "message"?: "<human sentence>"
}

Code	Status	Description
`unauthorized`	401	The token is missing, malformed, unknown, expired, or revoked. All auth failures return this single code with no further detail.
`insufficient_scope`	403	A `read` token was used on an endpoint that requires `read-write`.
`email_unverified`	403	The token is valid, but your account email is not verified. Verify your email, then retry.
`rate_limited`	429	You exceeded the read or write cap. The response carries a `Retry-After` header (whole seconds) telling you when to retry.

One 401 for every auth failure

A missing, malformed, unknown, expired, or revoked token all collapse to the same 401 unauthorized. The response does not tell you which one it was, so check the token itself if a call you expected to work returns 401.

Keep tokens safe

Treat a token like a password

A token is a credential to your account. A read-write token grants full read-write access to all of your diagrams, so handle it the way you would any secret.

Never commit a token to source control or paste it into a shared chat.
When you sign in with the CLI, the token is stored at ~/.config/excaliwow/config.json with owner-only (600) permissions.
Revoke a token any time from Settings, then Developer / API tokens. A revoked token stops working immediately.