How to create and manage an API key
Create an API key in Settings, API, then copy, rename or delete it whenever you need to.
An API key lets your own code, a tool or an AI assistant work with Tarkle as the person who made it. This article shows how to create a key in Settings, copy it, rename it and delete it, and how to send it with a request. Only the owners and admins of an organization can manage keys. A member who needs one asks an owner or admin. Roles are explained in Teams, roles and sharing files with your team.
Create a key
Open API in Settings. The API keys tab lists every key of your organization.
Click Create.
In Name, type a name you will recognise, such as "Production API". A name can be up to 80 characters.
Under Access, keep All workspaces. To limit the key, choose Only selected workspaces, then tick the workspaces under Choose workspaces.
Click Create.
Under Token, click the key to copy it, then click Done.
A key does not expire. It works until you delete it. Tarkle also emails the person who made the key when it is created. The dialog reminds you that you can copy the key again later, and the sections below show how.
What a key can do
A key can do everything the API and the MCP server can do in the workspaces it reaches. That covers files and folders, transfers, file requests, brand pages, contacts, team folders, members and webhooks, both reading and changing them. It acts as the person who made it. A key cannot make purchases.
Tarkle checks the creator's access to each workspace on every request, so when someone loses access to a workspace, the keys they made stop reaching it too. For brand pages through the API, the person who made the key must also be an owner or admin of that workspace.
A key set to Only selected workspaces reaches only the workspaces you picked. Any other workspace answers with status 403 and the code no_access, and an AI assistant connected with that key does not list those workspaces.
Send the key with an API request
Send the key in the Authorization header as a bearer token: Authorization: Bearer <your-tarkle-key>. The Developer API page describes what you can build with it, and What is the Tarkle API? explains how requests are made. The API reference in the developer documentation lists every request you can send.
Requests that work inside a workspace also name it with its workspace key, in the X-Workspace-Key header. A workspace key is eight lowercase letters and digits.
Connect an AI assistant
ChatGPT, Claude and Grok connect to the MCP server by signing in to Tarkle in the browser, so they need no key. A coding assistant such as Claude Code, Codex, Cursor, VS Code or Windsurf uses the same key: add Authorization: Bearer <your-tarkle-key> to its connection to https://mcp.tarkle.com/mcp. The connect an AI assistant article explains both ways, and the MCP server page describes what an assistant can do with your files.
Copy, rename or delete a key
Open API in Settings.
Click the three dots at the end of the key's row.
Click Copy token, Rename or Delete.
Copy token copies the key to your clipboard. Only owners and admins can copy a key. Rename opens the Rename key dialog: change Name, then click Save. Delete opens the Delete key dialog, and you click Delete there. A deleted key stops working right away, everywhere it is used. Put the new key in your tool before you delete the old one.
Note: a key with the Legacy badge was made before API keys had full access. It keeps its old, limited permissions and cannot connect to the MCP server. A key made before copying existed has no stored copy, so its Copy token is turned off. Create a new key to get full access and a key you can copy.
When a request is refused
Status 401 with the code
unauthorized: the key is missing, mistyped, or deleted.Status 401 with the code
legacy_token: the token is an older workspace token that no longer works. Create a new key in Settings, API.Status 403 with the code
no_access: the key cannot reach that workspace, or the person who made the key cannot access it.Status 400 with the code
workspace_required: the request names no workspace. Send theX-Workspace-Keyheader.
What happens next
After the key is in your tool and makes its first request, the Last used column shows when it was last used. Until then the column shows Never.