Começar
Autenticação
Bearer token, os 10 escopos, allowlist de IP, os 60 segundos de propagação e o 429 que substitui o 401.
Toda chamada autenticada leva um token no header Authorization. São duas credenciais possíveis: a chave de API do workspace (gos_…), o assunto desta página, ou o token de um usuário que entrou pelo seu app — esse é o login de usuário (OAuth2). Sem token válido: 401 unauthorized.
Os dois headers
Authorization: Bearer gos_… (preferido) e X-API-Key: gos_… são equivalentes — se os dois vierem, o Authorization ganha. É o prefixo gos_ que decide o caminho: com ele, o token é tratado como chave de API e conferido contra esta página inteira; sem ele, como token de login de usuário, que tem as regras dele. Token de formato desconhecido nos dois caminhos é 401.
Os escopos que existem
São 10. Marque só os que a integração usa; o que não estiver marcado responde 403 forbidden_scope nomeando exatamente o que falta — nunca um 404 disfarçado.
Para saber o que a sua chave alcança sem descobrir rota a rota pelo 403, chame GET /me: responde a qualquer credencial válida, sem exigir escopo, com o workspace, a chave (id, nome, validade) e a lista de escopos dela. Nunca devolve o token.
| Escopo | Dá acesso a |
|---|---|
contacts.read | /contacts, /contacts/:id, /tags, /tasks, /interactions, /custom-fields?entity=contact |
contacts.write | POST /contacts, /contacts/upsert, PATCH /contacts/:id, /contacts/:id/tags, /contacts/:id/notes, DELETE /contacts/:id, POST /tasks |
pipelines.read | /pipelines |
opportunities.read | /opportunities, /opportunities/summary, /opportunities/:id, /opportunities/:id/history, /opportunity-events, /custom-fields?entity=opportunity |
opportunities.write | POST /opportunities, PATCH /opportunities/:id, /move, /win, /lose, PUT /opportunities/:id/custom-fields |
calendars.read | /calendars, /calendars/:id/slots, /appointments, /appointments/:id, /appointments/:id/history |
calendars.write | POST /appointments, /reschedule, /cancel, /outcome |
users.read | /users |
webhooks.manage | o CRUD de /webhooks e /webhooks/:id/deliveries — assinar um evento exige também o escopo de leitura dele |
platform.read | /platform/users, /platform/users/:id. Exclusivo da conta Accelera: não aparece na tela e, mesmo concedido, outro workspace leva 403 forbidden_platform |
Allowlist de IP (opcional)
Uma chave pode ser restrita a uma lista de IPs exatos (sem CIDR). Vazio = sem restrição, o comportamento padrão. Fora da lista: 403 forbidden_ip — checado antes do escopo, pra mensagem de escopo não vazar pra quem nem devia estar ali. Toda recusa por IP também dispara um alerta interno de uso anômalo.
Expiração, rotação e revogação
Chave nova expira em 1 ano por padrão (dá pra escolher 90 dias ou nunca); chave expirada é 401. Rotacionar gera um token novo e mantém o antigo válido por 24 horas — a menos que você marque "revogar já" — pra você trocar no seu sistema sem downtime: troque, confirme, e só então revogue. A rotação mantém o mesmo id de chave, então auditoria e métricas não se partem, e cada autenticação pelo token antigo fica registrada no nosso log. Revogar é definitivo: chave revogada não volta, não pode ser editada nem rotacionada — crie outra.
Os 60 segundos de propagação
O resultado da checagem da chave fica em cache por 60 segundos. Isso vale pra tudo que você mexer nela: revogar, rotacionar, editar escopos, mudar a allowlist de IP. Depois de alterar a chave, espere até um minuto antes de concluir que não funcionou.
Os dois 403 que não são de escopo
403 workspace_suspended significa que o workspace está pausado: a chave está perfeita, a conta é que não está ativa — retry não resolve, e nenhuma rota responde enquanto isso durar. 403 forbidden_platform significa que /platform/* foi chamado por uma chave que não é do workspace da Accelera: também não é erro de configuração, a rota é exclusiva daquela conta.