API tokens and webhooks
Create, rename and delete API tokens, and add webhook endpoints, on Settings > API.
API tokens let a tool outside Tarkle connect to your account. Your own code, the Tarkle WordPress plugin and the Brand API can each use one. Webhooks send a signed request to an address you choose when something happens to a brand page. Both are managed on the API page, Settings > API.
Tarkle turns Settings > API on for all accounts at once. Until then the page is not found.
Open Settings > API
Open Settings > API. The page lists your developer tokens and MCP tokens in one table, newest first. Below the table is the Webhooks section, which works on one workspace at a time. A developer token belongs to your account, not to one workspace, and it works for every workspace you can access.
Create a developer token
Click New token.
If the dialog asks which kind of token to make, click Developer token. The MCP token card appears only when Tarkle has switched MCP on for your account.
In Token name, type a name you will recognise, such as Production API.
Under Public API access, tick each access the token needs.
Click Create token.
In Token (shown once), click the token to copy it, then click Done.
The access choices are these:
brands:read: Read brands, their assets, brand.md and analytics
brands:write: Update a brand's text, links, access and settings
brands:create: Create brands, delete them to the bin and restore them from it
brands:requests: List download and view requests and approve or reject them
webhooks:manage: Add, change and remove webhooks, send test events and read the delivery log
files:read: List and download files and folders
files:write: Create folders, rename and delete files and folders (and restore them from the bin); uploads are separate calls
A token with no access selected cannot call the API. The WordPress plugin needs no access, so leave the boxes empty for it. Developer tokens do not expire. Each request names the workspace it works on, and the Brand API quick start shows the first calls.
Manage your tokens
The table has five columns: Name, Type, Token, Expires and Last used. Developer tokens show Never under Expires. To find a token, type its name, its type or the first characters of the token in the Search tokens... box.
Open the three-dot menu at the end of a row:
Rename opens Rename token. Change the Name and click Save.
Delete opens Delete token. Click Delete to confirm.
Deleting a token stops it at once, everywhere it is used. Create the replacement token and put it in your tool before you delete the old one.
Add a webhook
Webhooks belong to one workspace, and only an owner or admin of that workspace can add, change or remove its webhooks. If you have more than one workspace, choose the workspace above the Webhooks table first.
Under Webhooks, click the button that adds a webhook.
In Address, type an https:// address that is reachable from the internet.
In Description (optional), add a short name, such as Zapier.
Under Events, keep All events ticked. To send page views too, tick Also send page views. To choose events one by one, untick All events and tick each event you need.
Click the button that saves the webhook.
In Signing secret (shown once), click the secret to copy it, then click Done.
The events come from brand pages: page views, downloads, brand edits, new access requests, and access requests approved or rejected. All events does not include page views. Use the signing secret to check the Tarkle-Signature header on each request.
Manage webhooks
Each row of the webhook table shows its address, its events, whether it is On or Off, and when it was Last delivered. Open the row's menu for these actions:
Send test sends a test event to the address and shows the answer it gave.
Deliveries lists the latest events sent to the address, kept for 7 days. Click Send again to send one again. It works only while the webhook is on.
New signing secret makes a new secret. The old one keeps working for 24 hours.
Turn off pauses the webhook, and Turn on starts it again.
Delete removes the webhook and its delivery history, and events stop being sent to it.
What happens next
Once a webhook is on, Tarkle sends it the events you chose. A delivery that fails is tried again, and the row shows Failing: retrying until a delivery succeeds. The Last delivered column shows Never until the address answers a delivery.