Autenticação

Chaves API

O AdaptlyPost utiliza chaves API para autenticar pedidos REST API. Pode gerar e gerir chaves API a partir do seu painel em Definicoes > API Tokens.

Utilizar a Sua Chave API

Inclua a sua chave API no cabecalho Authorization de cada pedido:

Authorization: Bearer your_api_key_here

Pedido de Exemplo

curl https://post.adaptlypost.com/post/api/v1/social-accounts \
  -H "Authorization: Bearer adaptly_8f3c1d9a7b2e4605c1a8d7f36b904e2d"

Papéis e permissões

Cada membro de um espaço de trabalho tem um de quatro papéis. O papel decide o que o membro pode fazer no painel e o que qualquer chave de API, sessão MCP ou integração que age em seu nome pode fazer. A verificação roda no servidor a cada requisição, então um cliente não consegue contorná-la.

Permissões por papel

Cada página de endpoint indica a permissão necessária. Uma chave tem exatamente as permissões do seu papel, menos o que seu criador não pode mais fazer. GET /api/v1/me devolve a lista.

As chaves carregam um papel

Ao criar uma chave você escolhe o papel dela. A chave passa a agir com esse papel no espaço de trabalho em que foi criada, segundo estas regras:

• Uma chave nunca pode ser criada com um papel acima do papel do membro que a cria. Um Editor pode emitir chaves de Editor, Colaborador ou Visualizador, não de Administrador.
• A cada requisição, as permissões efetivas da chave são as do seu papel, menos o que seu criador não pode mais fazer. A verificação lê o papel atual do criador, não o papel no momento da criação.
• Se o criador for rebaixado, todas as chaves que ele criou encolhem junto na hora. Uma chave de Editor criada por um membro que agora é Colaborador só consegue criar rascunhos.
• Se o criador sair do espaço de trabalho ou for removido, suas chaves param de funcionar e respondem 401 com code token_issuer_lost_access. Um administrador do espaço de trabalho cria uma substituta.
• Uma sessão MCP ou concessão OAuth não tem papel próprio: age com o papel do membro que entrou no espaço de trabalho em que a chamada cai. É o espaço de trabalho padrão desse membro, a menos que X-Workspace-Id indique outro.

Escolhendo um espaço de trabalho

Um membro pode fazer parte de vários espaços de trabalho, em uma ou várias organizações. Uma conexão OAuth, como o conector do Claude ou do ChatGPT, pode agir em qualquer um deles. Uma chave de API age apenas no espaço de trabalho em que foi criada. Envie o cabeçalho opcional X-Workspace-Id em qualquer requisição para escolher o espaço de trabalho. Sem ele, a chamada cai no espaço de trabalho padrão.

X-Workspace-Id: ag_02k7m

Este endpoint lista os id de espaço de trabalho que você pode enviar, com o seu papel e um objeto can para cada um: GET /api/v1/workspaces

Erros de Autenticacao

Uma chave ausente, inválida ou expirada responde 401. Uma chave que existe mas não pode fazer o que você pediu responde 403. Todo corpo de erro traz um code legível por máquina para que um cliente os distinga:

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

A chave é válida, mas o membro que a criou não pertence mais ao espaço de trabalho. A chave está morta de vez; peça uma nova a um administrador do espaço de trabalho.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "token_issuer_lost_access",
  "message": "This API key no longer works: the member who created it lost access to the workspace. Ask a workspace admin for a new key."
}

Um início de sessão OAuth, como o conector do Claude ou do ChatGPT, usou um e-mail sem conta AdaptlyPost. Desconecte o app e conecte de novo com o e-mail que você usa na AdaptlyPost.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "oauth_account_not_found",
  "message": "You signed in as jane@example.com, which has no AdaptlyPost account. Disconnect this app and connect again with the email you use on AdaptlyPost."
}

O papel da chave não tem a permissão que esta operação exige. O corpo indica a permissão em falta, o papel com que a chave age e o que fazer em vez disso. Numa operação sobre publicações, a permissão exigida depende da requisição: publicar agora exige posts.publish, um scheduledAt futuro exige posts.schedule, e mexer na publicação de outro membro exige também posts.others.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "permission_denied",
  "requiredPermission": "posts.publish",
  "role": "contributor",
  "keyRole": "contributor",
  "issuerRole": "editor",
  "tokenType": "api_token",
  "message": "The Contributor role cannot publish posts. Send the post with saveAsDraft: true and ask a workspace member to publish it."
}

O plano da organização não está ativo ou não inclui acesso à API. Cada chamada com a chave ou com o início de sessão OAuth recebe esta resposta até o plano ser renovado ou melhorado. code distingue este 403 dos outros.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "subscription_required",
  "message": "This API key no longer works: your organization's plan does not include API access. Renew or upgrade the plan to use it again."
}

X-Workspace-Id indica um espaço de trabalho que quem chama não alcança. Uma chave de API recebe a mesma resposta para qualquer espaço de trabalho que não seja o dela. Envie um id de GET /api/v1/workspaces ou omita o cabeçalho.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "ag_03p4r",
  "message": "You have no access to workspace ag_03p4r. Call GET /workspaces to list the workspaces you can use, and send one of those ids in the X-Workspace-Id header."
}

Para equipes reguladas

Um assento de Colaborador e uma chave de Colaborador são aplicados no servidor, não na interface. Cada requisição, venha do painel, da API REST, do servidor MCP ou de uma integração como Zapier ou n8n, passa pela mesma verificação de permissões no serviço de publicações antes de qualquer gravação: a verificação lê o papel de quem chama no espaço de trabalho naquele momento, deduz a permissão necessária a partir dos fatos da requisição (rascunho, agendada ou publicar agora; publicação própria ou de um colega) e recusa com 403 quando ela falta. Uma chave é criada sob um papel, nunca acima do membro que a cria, e suas permissões são recalculadas a cada chamada como a interseção entre o papel da chave e o papel atual do criador, então rebaixar o criador encolhe a chave na hora e removê-lo a mata. Um auditor pode apontar para três coisas: GET /api/v1/me, que devolve o papel e a lista exata de permissões que uma chave tem agora; o corpo do 403, que nomeia a permissão em falta, o papel que não a tinha e o tipo de token que tentou; e a trilha de auditoria de publicações, onde cada tentativa de criar, agendar, publicar, repetir ou excluir fica registrada com quem fez, por qual chave, sob qual papel, de qual status para qual, e se foi permitida ou recusada. A trilha é gravada pelo serviço de publicações; ainda não pode ser consultada no painel nem pela API.