Autenticação e chaves

Cada chamada à API usa uma chave secreta no header HTTP Authorization:

Authorization: Bearer SUA_CHAVE

Gerar uma chave

1. Entre no painel da OctoSolve com um usuário owner ou administrador da conta.
2. Abra Configurações > API e integrações.
3. Clique em Criar chave.
4. Dê um nome que identifique a integração.
5. Escolha o escopo read ou write.
6. Se quiser, defina uma data de validade.
7. Copie a chave no momento da criação. O segredo completo é exibido uma única vez.

As chaves de produção começam com osk_live_ e seguem este formato:

^osk_live_[A-Za-z0-9_-]{43}$

O prefixo osk_test_ está reservado para um ambiente de teste futuro e ainda não é aceito.

Escopos

Uma chave da API não pode criar, listar, reativar ou revogar outras chaves. A gestão de chaves exige uma sessão de usuário no painel.

Validade, suspensão e revogação

A validade é opcional. Uma chave vencida responde 401 unauthorized, exatamente como uma chave revogada ou inexistente. Essa resposta indistinguível evita revelar quais chaves já existiram.

Ao fazer downgrade para um plano sem API, as chaves são suspensas. Elas não voltam a funcionar automaticamente em um upgrade. Um owner ou administrador precisa reativar cada chave elegível no painel.

A revogação é definitiva. Ela costuma valer imediatamente, mas pode levar até 60 segundos por causa do cache de autenticação. Requisições que já foram autenticadas e estão em andamento podem terminar.

Exemplo com curl

curl --request GET \
  --url "https://api.octosolve.com.br/api/v1/contacts?limit=10" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Accept: application/json"

Sem um header válido, a resposta é 401 e inclui WWW-Authenticate: Bearer.

Receita para Make ou n8n

1. Crie uma credencial ou variável secreta chamada OCTOSOLVE_API_KEY.
2. No módulo ou nó HTTP, configure Bearer token com essa credencial. Se a ferramenta não oferecer esse tipo, adicione Authorization: Bearer SUA_CHAVE nos headers.
3. Não concatene a chave na URL.
4. Para um cenário que apenas consulta contatos, prefira uma chave read.
5. Para criar ou atualizar contatos, use uma chave write.
6. Se receber 401, confira o segredo e a validade. Gere uma nova chave se a anterior foi revogada ou venceu.