An API key is the one credential for the Tarkle API and the MCP server. Owners and admins create, copy, rename and delete keys in Settings > API. This page covers those steps, what a key can do and what happens to keys made earlier.
Who can manage keys
Only the owner and the admins of an organization can open Settings > API. A member who opens it is sent back to Settings. Owners and admins see every key in the organization, including keys other people made.
Read the keys list
Open Settings > API. The page has two tabs, API keys and Webhooks. Each key is one row with these columns:
- Name: the name the key was given. A Legacy badge marks an older key. See Keys made before this change below.
- Access: All access, or the avatars and names of the workspaces the key may reach. Up to three avatars are shown, then a +N count for the rest.
- Created by: the person who made the key. Your own keys show “me”.
- Token: the start of the key, followed by dots. The full key is never shown in the list.
- Last used: when the key last made a call, or Never.
The menu at the end of each row (the three dots) holds Copy token, Rename and Delete.
Create a key
- Open Settings > API and click Create.
- In Name, type a name of up to 80 characters.
- In Access, choose All workspaces or Only selected workspaces. For the second choice, open the workspace list and tick at least one workspace.
- Click Create.
Tarkle shows the key in the API key created dialog. Click the key to copy it. Tarkle also emails the person who made the key that a new key was created.
Choose the access
All workspaces lets the key reach every workspace that the person who made it can reach, including workspaces created later. Only selected workspaces lets it reach the workspaces you tick and no others. A call to any other workspace answers 403 no_access, the same answer Tarkle gives for a workspace key that does not exist, so keys cannot be probed. See no_access.
What a key can do
A key holds every permission of the API except billing:purchase: file calls (files:read and files:write), brand calls (brands:read, brands:write, brands:create, brands:domains, brands:files and brands:requests) and webhook calls (webhooks:manage). Each call reads or changes data in the workspaces the key reaches.
A call acts as the person who made the key, and Tarkle checks that person’s access to the workspace on every call. A brand call also needs that person to be an owner or admin of the workspace. A key does not hold billing:purchase.
A key stops working when it is deleted. If its creator can no longer reach a workspace, calls to that workspace answer 403 no_access.
Use the key
Send the key in the Authorization header with the word Bearer. A key starts with tk_.
curl -H "Authorization: Bearer <your-tarkle-key>" https://tarkle.com/api/v1/workspacesThis call lists the workspaces the key reaches. Each one has an eight-character workspace key. Send that key in the X-Workspace-Key header on every call that reads or changes something inside a workspace. A workspace id is refused in its place. The rules for the header are in Authentication.
Copy a key
The full key is shown once, when you create it. To copy it again, open the row menu and choose Copy token. Only owners and admins can copy a key. Tarkle keeps each key encrypted so that it can be copied again later.
A key made before copying existed has nothing to copy. Its Copy token item is disabled, and the reason is shown on hover. Create a new key to get one you can copy.
Rename a key
Open the row menu, choose Rename, type the new name, up to 80 characters, and click Save. Renaming changes only the name. The key, its access and its value stay the same.
Delete a key
Open the row menu, choose Delete, and confirm in the Delete key dialog. The key stops working right away, everywhere it is used. A call with it answers 401 unauthorized, and it can no longer be copied. Create a new key to replace it.
Keys made before this change
Keys already on the list keep working. A key with a Legacy badge was made before keys had full access. It keeps its old, limited permissions. A call outside that set answers 403 forbidden, and the MCP server does not accept the key. Create a new key to get the full set.
Old keys tied to one workspace do not appear in this list. A call with one answers 401 legacy_token. Create a new key in Settings > API to replace it.
Use the key with the MCP server
The MCP server accepts the same key. Coding assistants connect to https://mcp.tarkle.com/mcp and send Authorization: Bearer <your-tarkle-key>. A key limited to selected workspaces reaches only those workspaces through the MCP server too. Assistants that sign in through the browser need no key. See MCP server.
Webhooks
The Webhooks tab manages webhook endpoints. Webhooks send a signed request to your address when something happens in a workspace. Each endpoint belongs to one workspace, the one you choose on the tab. For the events, the signature and delivery, see Webhooks.
Get help
The API documentation link at the top of Settings > API opens these developer docs. For questions and examples, or to share what you build, join the Tarkle Slack community.