Autenticação

Toda requisição carrega um bearer token, obtido trocando uma credencial em POST /oauth/token.

A credencial é uma empresa, não um usuário

A credencial identifica a sua empresa. Ela não está ligada a uma pessoa, um login, um time ou um workspace selecionado, e não herda a permissão de ninguém. Tudo que o token lê tem o escopo da empresa para a qual foi emitido, e nenhum parâmetro amplia isso.

É por isso que não existe fluxo de login de usuário: não há usuário.

Obtendo um token

curl -X POST https://api.salesbud.com.br/oauth/token \
  -d 'grant_type=client_credentials' \
  -d "client_id=$SALESBUD_CLIENT_ID" \
  -d "client_secret=$SALESBUD_CLIENT_SECRET"

O endpoint aceita apenas application/x-www-form-urlencoded. A credencial também pode ir por HTTP Basic em vez de no corpo.

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "meetings.read calls.read transcriptions.read"
}

Os tokens são assinados em RS256 e carregam a empresa, os escopos concedidos e a versão da credencial.

Escopos

Escopo	Permite
`meetings.read`	Listar e obter reuniões, suas respostas de template e sua avaliação geral.
`calls.read`	Listar e obter ligações, suas respostas de template e sua avaliação geral.
`transcriptions.read`	Ler transcrições, junto com o escopo da coleção a que a transcrição pertence. Pedido à parte porque a transcrição é o dado mais sensível que a API serve.

A transcrição exige dois escopos: meetings.read e transcriptions.read para a transcrição de uma reunião, calls.read e transcriptions.read para a de uma ligação. transcriptions.read sozinho não lê nada.

O token recebe os escopos anexados à credencial. Chamar uma rota fora deles devolve 403 INSUFFICIENT_SCOPE — é o portão funcionando, não rota faltando.

Use GET /v1/context para ver os escopos que um token realmente carrega.

Tempo de vida e renovação

Os tokens expiram depois de expires_in segundos (3600 por padrão).

Não existe refresh token, por desenho. Client credentials é um fluxo máquina-a-máquina, sem usuário para reconsentir, então a RFC 6749 §4.4.3 diz para não emitir um — seria um segundo segredo de vida longa com o mesmo poder do primeiro. Renovar é chamar /oauth/token de novo.

Guarde o token um pouco abaixo do expires_in e reemita também quando uma requisição devolver 401 INVALID_ACCESS_TOKEN. Uma credencial pode ser revogada antes de o prazo acabar; só o relógio não percebe.

Rotacionando um secret

A rotação emite um secret novo e mantém o anterior válido por sete dias, para você fazer deploy do valor novo sem janela de erro.

No máximo dois secrets ficam válidos ao mesmo tempo. Revogue o que está expirando antes de iniciar outra rotação, senão a segunda é recusada com 409 ROTATION_IN_PROGRESS.

Revogar ou desabilitar o client inteiro invalida os tokens emitidos na hora — é essa a alavanca em caso de suspeita de vazamento, não a rotação.

Allowlist de IP

A credencial pode ter uma lista opcional de CIDRs IPv4/IPv6. Quando definida, ela é aplicada tanto na emissão do token quanto em toda requisição que o usa, então um token vazado não serve fora da sua rede.