Um token de API permite que o seu próprio código comunique com a Ocoya. Encontre-os em Settings → API — Settings está no menu da conta, o avatar no topo da barra lateral.
Esta página explica como gerir tokens. Para saber como chamar a API em si — o URL base, o header, os endpoints — veja a documentação da REST API.
Comece aqui. O menu da conta é o avatar no topo da barra lateral — Settings, depois API na barra lateral das definições.
Settings → API, com o gráfico de pedidos em cima e os seus tokens em baixo.
Who can use the API
O acesso à API é apenas para owners and admins de uma brand.
| Your role in a brand | Create tokens | A token reaches the brand |
|---|---|---|
| Owner | Yes | Yes |
| Admin | Yes | Yes |
| Manager | No | No |
| Client | No | No |
Um manager que precise de acesso à API para uma brand tem de ser tornado admin dessa brand pelo owner da brand (Settings → Members). Na app, a opção de API só aparece em Settings para owners e admins.
Create a token
Selecione Create token e dê-lhe um nome. O nome é apenas para si — serve para conseguir distinguir os tokens mais tarde e revogar o correto.
Dê nomes aos tokens com base onde são usados, não no que fazem. Zapier, servidor de staging, script de reporting dizem‑lhe o que é que vai falhar quando o revogar. API key 2 não diz.
Copie o token assim que for criado e guarde-o num local seguro. A Ocoya mostra apenas os primeiros e últimos caracteres a partir daí.
What a token can reach
Um token é seu e tem acesso a todas as brands de que é owner ou admin. Um único token cobre todas elas, incluindo brands em que passe a ser admin mais tarde. Não há forma de limitar o âmbito de um token a uma única brand — a lista de tokens mostra All brands em cada um.
As brands a que um token consegue aceder são verificadas em cada pedido, a partir do seu papel nesse momento. Se for removido de uma brand, ou deixar de ser admin, os seus tokens deixam de lhe aceder de imediato; se passar a ser admin de uma brand, passam a aceder‑lhe de imediato. Um token pode fazer tudo o que a API oferece em cada brand a que chega.
Isto é importante se estiver a pensar dar ao developer de um cliente um token apenas para a brand desse cliente. Não pode. Ele conseguiria aceder a todas as brands a que você consegue.
Um token funciona com tudo o que está na REST API: posts, campanhas de IA (criá‑las, listá‑las e lê‑las com os respetivos posts), o perfil e o brand score de cada brand, que também pode atualizar, channels e workflows.
Revoke a token
O menu ⋯ de qualquer token tem a opção Delete token. A eliminação é imediata e permanente — tudo o que estiver a usar esse token começa a falhar logo, por isso certifique‑se primeiro de que sabe o que é que o está a usar. É para isso que servem os nomes.
Não há forma de fazer a rotação de um token no mesmo lugar. Para substituir um: crie o novo token, aponte a sua integração para ele e depois elimine o antigo.
Watching usage
O gráfico API usage mostra os pedidos autenticados para a brand atual, na última hora, dia ou 30 dias. É a forma mais rápida de confirmar que uma integração está mesmo a chamar a Ocoya, ou de detetar uma que está a chamar muito mais do que esperava.
A Ocoya permite 60 requests per minute por key e devolve 429 Too Many Requests acima desse limite. Todos os detalhes, incluindo os headers de rate limit, estão em Rate limits.