Authentication
Personal API tokens, scopes, expiry and how your role applies.
Every request carries a personal API token in the Authorization header:
Authorization: Bearer hvt_…Tokens
- A token belongs to you and one workspace: the workspace you were in when you created it. To work in another workspace, switch to it in the app and create a token there.
- You create, see and revoke your tokens in Settings → API & MCP. A token is shown once, when it is created; Helvetly keeps only a hash of it, so a lost token cannot be shown again. Revoke it and create a new one.
- A token can expire after 30, 90 or 365 days, or never. An expired or revoked token answers
401. - You can have up to 20 tokens.
Scopes
A token's scopes say which areas of the API it may use, and whether it may only read or also change them:
| Scope | Allows |
|---|---|
read:* | Every read operation (GET) |
write:* | Every operation, reading and writing |
read:<area> | Reading one area, for example read:invoices |
write:<area> | Reading and changing one area, for example write:clients |
The areas are the sections of the API reference: clients, invoices, expenses,
documents, engagements, products and reports. Write implies read. Each operation's page names the scope
it needs. Calling an operation outside the token's scopes answers 403 with the code token_scope.
Give each token the least it needs: a reporting script needs read:* at most; an assistant that drafts invoices
needs write:invoices and read:clients.
Your role still applies
A token acts as you, with your current role and permissions in the workspace, checked on every request. If an owner limits what you may see or do, your tokens follow at once; if you leave the workspace, its tokens stop working.
A token can only call the operations in the API reference and the MCP server. Members,
billing, settings, your account and tokens themselves are only available in the app (403 token_not_allowed).
Try it in the browser
Each operation in the API reference has Try in Playground: paste a token (a read:* one is
enough to look around) and send a real request to your workspace. The token stays in that browser tab only (session
storage, gone when you close it) and is sent only to Helvetly. Write operations change real data.
Keep tokens safe
- Never put a token in code you commit, a URL or a shared document. Read it from an environment variable or a secret store.
- Use one token per script or tool, so you can revoke one without breaking the others.
- Revoke a token you no longer use, or one that may have leaked, in Settings → API & MCP.