Every call to the Tarkle API carries two things: a token that says who you are, and a workspace key that says where you work.
Tokens
Create a token in Settings > API. Send it on every request:
Authorization: Bearer tk_your_token- A token belongs to a person, not to a workspace. It acts as the person who created it, and never goes beyond that person’s role.
- Tarkle shows the full token once and stores only a hash. Create a new token if you lose it.
- Use tokens on a server. The API has no CORS headers, so a token in a browser is a leaked token.
- Tokens made before 2026-11-01 were bound to one workspace. They answer
401 legacy_tokenand must be replaced.
Workspace keys
A token on its own can call GET /workspaces. Everything inside a workspace needs the workspace named on every call, with the 8-character key (not the id):
| How | Example |
|---|---|
| Header | X-Workspace-Key: abcd1234 |
| Query | ?workspace_key=abcd1234 |
There is no default workspace. A missing key is 400 workspace_required, a malformed one 400 invalid_workspace, two different keys 400 conflicting_workspace, and a workspace id 400 workspace_key_required.
An unknown key, a workspace the token’s creator cannot reach and a closed workspace all answer 403 no_access, so keys cannot be probed.
Scopes
A scope lets a token read or change one kind of thing.
| Scope | Allows |
|---|---|
files:read |
List a folder, read a file or folder, get a short-lived download link, read storage use |
files:write |
Create folders, upload, rename, move, delete to the bin and restore |
brands:read |
List and read brands, their files, brand.md and analytics |
brands:write |
Update a brand’s text, links, colors, access and settings |
brands:requests |
List download and view requests and approve or reject them |
A token with no scopes answers 403 token_without_scopes. GET /workspaces works with any scope.
Roles
A scope is only half the check. On every call Tarkle also checks the creator’s current role in the named workspace. File calls follow the same rules as the app. Brand calls need an owner or admin. A creator who leaves a workspace loses it for the token at once.
Plans
API access is open to every plan. Each action is allowed or refused by the same plan limits as the app, so a call can answer 413 storage_full or 403 forbidden for the reasons the app would.
MCP tokens
The MCP server uses its own token type, created in Settings > API > New token > MCP token. MCP tokens expire after 30, 90 or 365 days.