TaleArt docs

Type a word to find a page, a heading or a sentence in the docs.

GitHub

API tokens

A personal API token lets a script, or the TaleArt command-line tool, call the Management API as you, without signing in with a passkey.

Create one

  1. In the dashboard, open Settings, then API tokens.
  2. Name it for what it does, pick All my projects or only some, keep Read-only unless the script must change things, and choose when it expires.
  3. Copy the token now. It starts tat_ and is shown only once: TaleArt keeps only a hash of it. Lost it? Revoke it and create another.

Use it

Send it in the Authorization header of each request:

curl -H "Authorization: Bearer $TALEART_TOKEN" https://your-taleart-api/api/v1/zones

Keep it in your script's secret settings, never in a page's HTML: a page uses a zone key (tak_) instead. A token works only on the Management API; zone keys and the project's site key (tas_, for servers) work only on the Delivery API.

Try it in the API reference, or let an AI agent use it through the taleart command-line tool: see AI agents. Give an agent a read-only token when its task only reads.

What a token can do

  • It acts as you, as you are at the time of each request: your role and your projects. It reaches the projects you gave it and can access, and nothing else. If you lose a project, the token loses it too.
  • A token for all my projects follows your role: if you are made an admin, it reaches every project from then on. Pick only some projects when a script needs only those.
  • A read-only token can read but never change anything.
  • An admin's read-write token can do what the admin can in its projects, including issuing, rotating and revoking zone keys and the project's site key, which can stop a page showing its zone. Give such a token only to scripts you trust with that.

What a token can never do

  • Create, list or revoke API tokens.
  • Sign in or out, set up TaleArt, or manage passkeys and sessions.
  • Invite people to a project.
  • Create a project, unless it is an admin's read-write token for all projects.

Those need you, signed in to the dashboard with one of your sign-in methods (a passkey, a password or a linked provider).

Revoke and limits

  • Revoke a token under Settings > API tokens; it stops working at once.
  • An admin can revoke every token of a person at once (for a lost laptop or someone leaving) with DELETE /api/v1/users/<user id>/api-tokens, signed in to the dashboard.
  • You can have up to 50 active tokens; expired and revoked ones do not count.
  • Too many wrong tokens from one address in a short time answer 429 for a while; a valid token keeps working.

Edit this page on GitHub