Autenticação
Tokens de API, permissões, tokens de um projeto, validade, revogação e o token de leitura do site.
Toda chamada se autentica com um token no cabeçalho Authorization:
Authorization: Bearer pl_live_...Uma chamada sem token, com um token desconhecido, expirado ou revogado recebe 401 com o código invalid_token (veja Erros e limites).
Tokens de API
São criados em Organização › Chaves de API por donos e admins da organização, em qualquer plano. Cada token tem:
| Campo | Opções |
|---|---|
| Nome | Até 80 caracteres, para você lembrar onde ele é usado. |
| Projeto | Um projeto da organização, ou Todos os projetos. |
| Validade | 30, 90 ou 365 dias, ou Nunca expira. |
| Permissões | Uma ou mais da tabela abaixo. |
O valor começa com pl_live_ e aparece uma vez, na criação. O Postline guarda só um resumo (SHA-256) e os quatro últimos caracteres, que a lista mostra. Se perder o valor, revogue e crie outro.
O token age com o papel atual de quem o criou: se essa pessoa sai da organização ou perde acesso a um projeto, o token perde junto. Uma ação que o papel não permite recebe 403 not_allowed.
Guarde o token no servidor
Um token de API age em nome da organização. Nunca o coloque em código que vai para o navegador, num repositório ou numa variável NEXT_PUBLIC_.
Permissões
Cada recurso tem recurso:read e recurso:write; aprovar um artigo tem a sua própria.
| Permissão | Libera |
|---|---|
projects:read | GET /projects, GET /projects/{id}/brand |
articles:read | GET /articles, GET /articles/{id} |
articles:write | Criar, atualizar, excluir, mandar para revisão e agendar artigos; POST /topics/suggest |
articles:approve | POST /articles/{id}/approve |
posts:read | GET /posts, GET /posts/{id} |
posts:write | Criar, gerar, atualizar, excluir, agendar e renderizar posts; gerar imagens de carrossel |
images:write | POST /images, DELETE /images/{id} |
comments:read | GET /articles/{id}/comments |
comments:write | POST /articles/{id}/comments, POST /comments/{id}/resolve |
calendar:read | GET /topics, GET /calendar |
results:read | GET /results |
Uma chamada a um endpoint cuja permissão o token não tem recebe 403 insufficient_scope. Dê a cada sistema só o que ele precisa.
Token de um projeto ou de todos
- De um projeto: só enxerga esse projeto. Ele já sabe o projeto: não mande
projectId. UmprojectIddiferente é recusado com403 project_not_allowed, e um id de outro projeto responde404 not_found. - De todos os projetos: enxerga os projetos que quem o criou alcança. As rotas de um projeto (
GET /articles,POST /articles,GET /posts,POST /images,GET /calendare outras) pedemprojectId, na query de umGETou no corpo de umPOST.
Validade e revogação
Um token expira no fim do prazo escolhido; a partir daí recebe 401 invalid_token. Em Organização › Chaves de API, Revogar desliga o token na hora, de vez. A lista mostra quando cada token foi usado pela última vez, e o painel Uso nos últimos 7 dias conta as chamadas e os erros.
Token de leitura do site
A leitura dos artigos publicados pelo seu site usa outro token, o de leitura do site (pl_read_…). Ele é emitido pelo npx @postline/cli init e fica em POSTLINE_READ_TOKEN. Com ele, GET /articles e GET /articles/{slug} respondem só os artigos publicados do projeto da integração, com locale obrigatório. Ele não faz mais nada.
Rodar o init de novo emite um token de leitura novo e uma chave de webhook nova. Veja Rotacionar as chaves.
Assistentes de IA
O servidor MCP não usa tokens de API: cada assistente se conecta por OAuth, em nome de quem autorizou.