---
title: "Authentication"
description: "How Tarkle API tokens, scopes and workspace keys work."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

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:

```http
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_token` and 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:create` | Create brands, delete them to the bin, list the bin and restore from it |
| `brands:files` | Upload a brand's icon, logos, banner, social image, favicon and collection files |
| `brands:domains` | Connect, check and remove a brand's custom domain |
| `brands:requests` | List download and view requests and approve or reject them |
| `webhooks:manage` | Add, change and remove webhook endpoints, send test events and read the delivery log |

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](/docs/mcp) uses its own token type, created in **Settings > API > New token > MCP token**. MCP tokens expire after 30, 90 or 365 days.

Source: https://tarkle.com/docs/get-started/authentication/index.mdx