An API token lets your own code talk to Ocoya. Find them under Settings → API — Settings is in the account menu, the avatar at the top of the sidebar.
This page covers managing tokens. For how to actually call the API — the base URL, the header, the endpoints — see the REST API documentation.
Start here. The account menu is the avatar at the top of the sidebar — Settings, then API in the settings sidebar.
Settings → API, with the request chart above and your tokens below.
Who can use the API
API access is for a brand’s owners and admins only.
| Your role in a brand | Create tokens | A token reaches the brand |
|---|---|---|
| Owner | Yes | Yes |
| Admin | Yes | Yes |
| Manager | No | No |
| Client | No | No |
A manager who needs API access for a brand has to be made an admin of it by the brand’s owner (Settings → Members). In the app, the API option is only shown in Settings to owners and admins.
Create a token
Select Create token and give it a name. The name is only for you — it’s there so you can tell tokens apart later and revoke the right one.
Name tokens after where they’re used, not what they do. Zapier, staging server, reporting script tells you what breaks when you revoke it. API key 2 doesn’t.
Copy the token as soon as it’s created and store it somewhere safe. Ocoya shows only the first and last few characters afterwards.
What a token can reach
A token is yours, and reaches every brand you own or are an admin of. One token covers all of them, including brands you’re made an admin of later. There’s no way to scope a token to a single brand — the token list shows All brands against each one.
Which brands a token reaches is checked on every request, from your role at that moment. If you’re removed from a brand, or stop being its admin, your tokens stop reaching it straight away; if you’re made an admin of a brand, they reach it straight away. A token can do everything the API offers in every brand it reaches.
That matters if you were planning to give a client’s developer a token for their brand only. You can’t. They’d be able to reach every brand you can.
A token works with everything in the REST API: posts, AI campaigns (create them, list them and read them with their posts), each brand’s profile and brand score, which it can also update, channels and workflows.
Revoke a token
The ⋯ menu on any token offers Delete token. Deletion is immediate and permanent — anything using that token starts failing straight away, so make sure you know what’s using it first. That’s what the names are for.
There’s no way to rotate a token in place. To replace one: create the new token, move your integration across, then delete the old one.
Watching usage
The API usage chart shows authenticated requests for the current brand, over the last hour, day or 30 days. It’s the quickest way to confirm an integration is actually calling Ocoya, or to spot one calling far more than you expected.
Ocoya allows 60 requests per minute per key, and returns 429 Too Many Requests beyond that. The full detail, including the rate-limit headers, is in Rate limits.