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 list shows 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, choose All workspaces. To limit the key, choose Only selected workspaces and pick 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 says you can copy the key again later, and the next sections 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, reading and changing files and brand pages. It acts as the person who made it. A key cannot make purchases. For brand pages, the person who made the key must also be an owner or admin of that workspace. Tarkle checks the creator's access on every request, so when someone loses access to a workspace, the keys they made stop reaching it too.
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 see 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.
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. The same key also works for the WordPress plugin.
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 that takes a token uses the same key: add Authorization: Bearer <your-tarkle-key> to the connection to https://mcp.tarkle.com/mcp. 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, so it keeps its old, limited permissions. It cannot connect to the MCP server. A key made before copying existed has no stored copy and cannot be copied either. 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 one that was made for a single workspace. It 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.