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.

To connect an AI tool like Claude rather than write your own script, see Connect an AI tool (MCP) — it creates and uses one of these tokens for you.

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 External connections section of the sidebar (just below the Library section) choose API tokens. 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 to diagrams and folders, including your teams' shared libraries. It can't manage teams (invites, roles, joining) or your account: those need you signed in to the app. Tokens created on this page are always full read-write; a token minted when you connect an AI tool can be read-only if you tick that option on the consent screen, and such tokens show a Read-only badge in the list here.
• 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.

For what you can call and how, see the Developers section: Authentication, worked examples, and errors and rate limits. The full machine-readable reference is published at /api/openapi.json.

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.