Autenticação

Toda requisição carrega um bearer token, obtido trocando uma credencial em POST /oauth/token, ou por um assistente de IA que faz você entrar com OAuth.

Duas espécies de credencial

Uma credencial é de empresa ou de usuário. As duas usam o mesmo fluxo OAuth, os mesmos escopos e os mesmos endpoints; o que muda é de quem são os dados que o token lê.

	Credencial de empresa	Credencial de usuário
Pertence a	A empresa	Uma pessoa da empresa
Lê	Tudo que é da empresa	O que essa pessoa vê no Salesbud, nada além
Quem cria	Quem gerencia as credenciais de API	Qualquer membro ativo que não aprova credenciais, com aprovação de um administrador. Um assistente que faz você entrar com OAuth também cria uma
Validade	Escolhida na criação, pode não expirar	30, 90, 180 ou 365 dias, contados a partir da aprovação. A conexão feita com OAuth não tem validade fixa
Uso típico	Integrações servidor a servidor, o conector MCP compartilhado	Um script pessoal, um cliente MCP local, o Claude ou o ChatGPT conectados por OAuth

Nenhuma das duas está ligada a uma sessão de login, a um workspace selecionado ou a um parâmetro: o que um token lê é decidido no servidor a partir da credencial, e nenhuma entrada amplia isso.

GET /v1/context diz qual espécie o token carrega em client.kind e, na credencial de usuário, quem é o dono em client.owner. Veja Obter o contexto da integração autenticada.

Solicitando uma credencial de usuário

1. Um membro de uma empresa com acesso à API solicita a credencial na tela de credenciais de API, escolhendo nome, escopos e validade. Só aparecem os escopos que o membro pode usar no Salesbud; os de e-mail e WhatsApp exigem o acesso correspondente lá.
2. O client ID e o secret aparecem uma única vez, nesse momento. A credencial fica inerte até ser aprovada: POST /oauth/token responde invalid_client.
3. Um administrador aprova ou nega o pedido como está. Os escopos não podem ser editados depois; outro conjunto de escopos é outra solicitação.
4. Aprovada, o mesmo secret passa a emitir token, e a validade de 30, 90, 180 ou 365 dias conta da aprovação, não do pedido. Pedido negado é revogado.

Quem aprova não recebe credencial de usuário. Quando um administrador, ou quem pode gerenciar as credenciais de API, faz o mesmo pedido, a tela de credenciais cria uma credencial de empresa ativa no lugar, sem validade, a menos que escolha 30, 90, 180 ou 365 dias.

Um assistente de IA também pode criar uma credencial de usuário para você fazendo você entrar com OAuth, em vez de copiar um secret. Essa conexão segue a mesma aprovação e os mesmos limites, com uma diferença: o aprovador que conecta recebe uma credencial de usuário ativa, não uma de empresa. Veja Conectar o Claude ou o ChatGPT.

Os apps da própria Salesbud, como os Colaboradores IA, conectam do mesmo jeito, com três diferenças: a empresa precisa da feature de colaboradores no lugar do acesso à API, e sem ela autorizar e renovar respondem 403 AI_COLLABORATORS_DISABLED; a conexão já nasce ativa, sem aprovação; e ela fica fora dos limites por usuário abaixo, sem contar neles. Ela aparece na tela de credenciais da API como qualquer outra conexão, e um administrador pode desativá-la ou revogá-la.

São 3 ativas e 1 pendente por usuário em cada empresa; credencial desativada conta como ativa. Credenciais de usuário não contam nas 20 credenciais ativas da empresa.

Quando o dono sai

Uma credencial de usuário só funciona enquanto o dono é membro ativo da empresa. Se o dono for desativado ou removido, ou não tiver mais login no Salesbud, POST /oauth/token responde invalid_client com "error_description": "The credential has no active owner.", e um token já emitido para de funcionar em até 60 segundos: as leituras respondem 401 INVALID_ACCESS_TOKEN. A credencial continua listada até um administrador revogá-la.

A conexão feita com OAuth não tem secret para apresentar, então falha de outro jeito: renová-la com o refresh token responde invalid_grant, não invalid_client.

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.

200 OK

{
  "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.

O token de uma credencial de usuário carrega os escopos pedidos menos os que o dono não pode usar no Salesbud no momento da emissão. Pedir um escopo que a credencial não tem continua recusado com 400 invalid_scope. Se o dono perder o acesso a e-mail, o próximo token sai sem os escopos emails.*, e o campo scope da resposta mostra isso. Se o dono perder a permissão de todos os escopos da credencial, o token ainda é emitido, com scope vazio, e cada leitura responde 403 INSUFFICIENT_SCOPE até a permissão voltar. A conexão feita com OAuth é mais rígida: quando nenhum dos escopos dela está disponível, o pedido de token é recusado com 400 invalid_scope, em vez de devolver scope vazio.

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

Tempo de vida e renovação

Na emissão, clientes manuais e apps OAuth de terceiros exigem API_ACCESS; apps OAuth próprios exigem AI_COLLABORATORS. Para empresas de parceiros, o parceiro também deve estar ativo e a oferta publicada deve conter a feature exigida pela credencial. Nessas empresas de parceiros, a mesma feature é revalidada a cada requisição autenticada: remover o acesso exigido recusa tokens de parceiros já emitidos com 403 API_ACCESS_DISABLED ou 403 AI_COLLABORATORS_DISABLED, conforme a credencial. A duração dos tokens legados permanece igual. Um header de workspace não troca a empresa vinculada à credencial.

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

Client credentials não têm refresh token, por desenho. É 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. Conexões feitas entrando com OAuth são diferentes: recebem refresh token, válido uma vez e por 90 dias, porque há uma pessoa por trás e nenhum secret para chamar 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.

Uma conexão feita com login termina com POST /oauth/revoke (RFC 7009): envie o refresh token dela, ou um dos access tokens, com o client_id do app. A conexão inteira é revogada, como na tela de credenciais da API, e a resposta é 200 com corpo vazio mesmo para um token que o servidor não conhece. Uma conexão que um administrador desativou continua desativada quando o dono ou o app a revoga: os refresh tokens acabam, mas só a revogação de um administrador a leva a revogada. Veja /oauth/revoke.

Rotacionando um secret

A rotação de uma credencial de empresa 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.

Só o dono rotaciona uma credencial de usuário. Um administrador pode desativá-la ou revogá-la, mas não rotacioná-la. Os sete dias acima valem só para credenciais de empresa: quando o dono rotaciona uma credencial de usuário, o secret anterior para de emitir token na hora, sem janela de sobreposição, e o secret novo tem validade de 30, 90, 180 ou 365 dias contada da rotação. Tokens já emitidos continuam valendo até expirar.

A conexão feita com OAuth não tem secret, então não pode ser rotacionada: o pedido é recusado com 409 OAUTH_CLIENT_NOT_ROTATABLE. Para cortá-la, revogue.

Numa credencial de empresa, 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.

O secret aparece uma vez

Ele é guardado só como hash HMAC-SHA256 com pepper do serviço e não pode ser lido de volta. Se for perdido, rotacione — não há caminho de recuperação.