Authentication

Every call to the Tarkle API is made with one credential, the API key. The Settings page says the same key works for the MCP server and rclone.

One key for the whole API

The Create dialog asks for a name and for the workspaces the key reaches. A key can read and change everything in the workspaces it reaches. It acts as the person who made it.

A key cannot buy a plan. POST /api/v1/purchases answers 403 forbidden.

Who can make a key

Only the owner or an admin of the organization can see, make, copy, rename or delete keys. Open Settings, then API. The page has two tabs, API keys and Webhooks. A member who opens the page is sent back to Settings.

Create a key

1. Go to the API keys tab.
2. Click Create to open the form.
3. In Name, type a name of up to 80 characters.
4. Under Access, pick All workspaces.
5. Or pick Only selected workspaces, then tick at least one workspace under Choose workspaces.
6. Click Create.
7. The dialog shows the new key. Click the key to copy it.

All workspaces covers every workspace the person who made the key can reach. You can copy the key again later from its menu, as described under Copy, rename and delete a key.

Send the key

Send the key in the Authorization header of every call, against https://tarkle.com/api/v1:

Authorization: Bearer <your-tarkle-key>

A key starts with tk_. Calls that read or change anything inside a workspace also name that workspace by its 8-character workspace key, in the X-Workspace-Key header or the workspace_key query parameter. Send the workspace key, never the workspace id: an id is refused with 400 workspace_key_required. A call that names no workspace key answers 400 workspace_required.

GET /api/v1/workspaces lists the workspaces the key can use, each with its workspace key. Send only the key:

curl https://tarkle.com/api/v1/workspaces \
  -H "Authorization: Bearer <your-tarkle-key>"

{
  "workspaces": [
    {
      "workspace_key": "abcd1234",
      "name": "Acme Studio",
      "url": "acme-studio",
      "relationship": "owner"
    }
  ]
}

relationship tells how the person who made the key reaches the workspace: owner, member or linked.

How a request is checked

Tarkle checks each call in this order.

1. The key exists and has not been deleted. Otherwise the call answers 401 unauthorized.
2. A key that was bound to one workspace answers 401 legacy_token. Create a new key instead.
3. The key holds the permission the call needs. Every key holds all of them except the permission to buy a plan. Otherwise the call answers 403 forbidden.
4. A restricted key reaches only the workspaces it was given. Any other workspace answers 403 no_access, and so does a workspace key that does not exist, a closed workspace, or a workspace the person who made the key cannot reach.
5. A suspended workspace answers 403 workspace_suspended.
6. Tarkle checks the role of the person who made the key on every call. A person who leaves a workspace loses the key’s access there. Brand calls need an owner or admin of that workspace. Any other role answers 403 forbidden.

Errors

Restricted keys

A restricted key is a key made with Only selected workspaces. GET /api/v1/workspaces lists only the workspaces you chose. Through the MCP server, a restricted key cannot create a workspace either.

Copy, rename and delete a key

Every key has a menu, opened from the three-dot button labelled Key actions. Only the owner or an admin can use it.

• Copy token copies the key again. Tarkle keeps the key encrypted, so it can be copied again. Keys made before copying existed have Copy token turned off: create a new key for those.
• Rename changes the key’s name.
• Delete stops the key at once, everywhere it is used. A deleted key cannot be copied again.

The list also shows each key’s Access and when it was last used.

Legacy keys

Keys made before the one-key change keep working with the permissions they were made with. The list marks them with a Legacy badge. A Legacy key can do only what its permissions allow. The MCP server does not accept it, so create a new key for full access. Some Legacy keys cannot be copied, because they were made before copying existed.

Keep the key safe

Treat the key like a password.

• Store it in an environment variable on your server, not in source code, and never in code that runs in a browser.
• Make one key per integration, so you can delete one without stopping the others.
• Delete keys you no longer use.

MCP server

Coding assistants connect to the MCP server at https://mcp.tarkle.com/mcp with the same key: Authorization: Bearer <your-tarkle-key>. See the MCP server page for the setup.

Related

• API overview
• Workspaces
• MCP server
• Managing API keys in the help center