API Tokens

An API token lets your own scripts and integrations talk to the livediagram API as you, outside the editor. A token carries your account's full read and write access, so treat it like a password.

You need an account

API tokens are a signed-in-only feature. The canvas, sharing, and real-time collaboration all stay account-free for guests, but tokens require signing in, the same as teams. Programmatic API access is an advanced, opt-in capability, so needing an account for it is a fair trade. On a self-hosted instance that hasn't enabled accounts, the feature simply isn't there.

Creating a token

Open the Explorer, and in the Library section of the sidebar choose API tokens (just under Themes). Give the token a name (for example, "CI bot") and create it.

The token's secret is shown once, right after you create it. Copy it then, because for your security it is never displayed again, here or anywhere else. If you lose it, revoke it and create a new one.

What a token can do, and for how long

• Access: a token has your account's full read + write access. There is no read-only option yet.
• Lifetime: every token lasts six months, then expires. There is no never-expires option. Rotate by creating a fresh token before the old one lapses.
• Limit: you can have up to 10 live tokens at once. Revoke one (or let it expire) to free a slot.

Using a token

Send the token as a bearer header to the API, which lives under /api on your livediagram host (https://livediagram.app/api on the hosted service):

# List your diagrams
curl https://livediagram.app/api/diagrams \
  -H "Authorization: Bearer lvd_your_token_here"

Every request authenticated this way acts as your account, with the same read and write access you have in the editor, so the endpoints behave just as they do for the app. Keep the Authorization header on each request; there is no separate login step.

Revoking a token

Revoke a token from the same API tokens section any time. Revocation is immediate: the next request that token makes is rejected. Deleting your account also removes all of your tokens, along with the rest of your data.