Authentication & access tokens

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 pick its capabilities (see below).
• Copy the token immediately. It is shown once, so store it somewhere safe before you leave the page.

Capabilities

A token holds a set of capabilities — any subset of the four below, chosen when you mint it. Pick the narrowest set that does the job: a token that only ever reads diagrams should hold just read; an agent that creates and edits needs read + write and nothing more.

Calling an endpoint without the capability it requires returns 403 insufficient_scope. Capabilities are fixed at mint time — to broaden a token's access, mint a new one and revoke the old.

Capabilities bound what a token may do; which diagrams it reaches follows your account's access. A token can read and edit (by id) diagrams you own, diagrams shared with you directly, and diagrams in a workspace you're a member of — your role there sets the ceiling, with editor access required for edits. delete and publish act only on diagrams you own, and anything outside your access answers 404 not_found.

Authenticate a request

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

Authorization: Bearer <token>

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

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

# 200 OK
# {
#   "id": "<userId>",
#   "email": "you@example.com",
#   "capabilities": ["read", "write", "publish", "delete"],
#   "scope": "read-write"
# }

The scope field is a legacy coarse summary kept for older clients: read-write when the token holds every capability, otherwise read. Use capabilities in new integrations.

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:

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:

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:

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": "<machine_code>",
  "message"?: "<human sentence>"
}

Keep tokens safe