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. So does the livediagram CLI when you sign in with livediagram auth login.
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 Settings (the gear near the end of the bottom bar, just before the Appearance toggle, in the editor or the Explorer) and choose Account, then API Tokens beneath it. You can also get there from Manage API Tokens in the AI Tools category, where that category is shown.
The first time, the form to create one is already open; after that, choose New beside the API Tokens title. Name it under What Is It For? (up to 60 characters, or pick a suggestion: Claude, Cursor, CI Bot or Local Script), and choose Create Token. The form shows the date the token will expire before you create it. The meter at the top shows how many of your ten slots are in use.
The token's secret is shown once, right after you create it. Copy it then with the copy button at the end of the field, because for your security it is never displayed again, here or anywhere else. Choose Done when you have it. If you lose the secret, revoke the token 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 documents 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 in Settings are always full read-write; a token minted when you connect an AI tool can be read-only if you switch on Read-only access on the approval page, 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 tokens at once. Revoke one to free a slot. An expired token stays in the list until you revoke it, and Settings still counts it toward the ten, so revoke expired tokens to make room.
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 documents
curl https://livediagram.app/api/documents \
-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. A few rules are particular to tokens: edits go through changesets rather than whole-tab saves, a token can't delete a document's last tab, and each token has its own rate limits. 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.
Viewing and revoking tokens
Every token you haven't revoked is listed in the same API Tokens category, newest first, with when it was created and when it was last used (a green dot means in the last day; Never used until its first request). A bar under each one shows how much of its six months has passed, with Active, Expires soon in amber once it has under two weeks left, or Expired in red. Workbenches paired with a token are listed on its card, where you can unpair them. To revoke one, choose the bin at the end of its card (its tooltip says Revoke) and confirm.
Revocation is immediate: the next request that token makes is rejected. In the last week before a token expires, an email reminds you once (where the deployment sends email), and a note appears on your Explorer Timeline. Deleting your account also removes all of your tokens, along with the rest of your data.
Keep tokens out of source control and shared logs. If one might have leaked, revoke it and create a replacement, no need to change anything else about your account.
Was this article helpful?