Autenticação

Como o SDK a recebe

Sem argumento nenhum, o SDK lê TRIVO_APP_TOKEN e TRIVO_BASE_URL do ambiente — e é assim que deve ser. Ele nunca põe a credencial em query string, e é ele quem carimba o cabeçalho em toda chamada, no REST e no gateway.

import { createApp } from "@trivo/sdk";

const app = createApp();

// Se o seu cofre entrega o segredo em memória, passe SÓ o que ele entrega: o
// que você não passa continua vindo do ambiente. O que não existe é o caminho
// confortável de deixar o segredo escrito no código.
const outro = createApp({ token: await cofre.ler("trivo") });

A forma do token

trivo_app.<Application ID>.<segredo>

O Application ID viaja no prefixo, e isso é de propósito: o Trivo identifica o App antes de abrir o banco, e você não precisa configurar o mesmo id duas vezes. O segredo é a parte que importa; o id não é secreto e aparece no portal ao lado do nome do App.

O Trivo guarda o sha256 do token, nunca o token. Revogar não apaga a linha: a credencial antiga morre e as conexões que ela abriu caem na hora.

O smoke: a primeira chamada

await app.rest.whoAmI();
// → { app: { publicId: "1234567890123456789", name: "Meu Bot" } }

É a chamada que responde "a sua credencial funciona" sem efeito nenhum. A recusa é uma só, sem distinguir o porquê: token inexistente, revogado ou de conta dona sancionada levantam TrivoError com MISSING_CREDENTIAL e a mesma frase. Quem sonda não aprende nada.

Duas vagas, para rotacionar sem queda

Cada App tem até duas credenciais vivas ao mesmo tempo, e é isso que permite trocar de segredo sem o bot ficar fora do ar. A ordem importa:

• emita a segunda credencial no portal e guarde o token, que aparece uma vez;
• suba o seu processo com ela e confira que ele autentica;
• só então revogue a primeira, pela ficha do App.

Não é um "client secret", e o nome não finge que é: são duas credenciais do mesmo tipo e do mesmo poder. O gesto de trocar credencial continua existindo e é o oposto deste — ele mata a atual na hora, e serve a quem vazou um segredo e quer o vazamento fechado já.

O que derruba uma credencial

• Trocar a credencial. A antiga morre no instante em que a nova nasce, e as conexões abertas por ela recebem CREDENTIAL_REVOKED antes de cair. Revogar uma das duas vagas derruba só as conexões daquela vaga.
• Exclusão do App. A credencial cai junto, com APP_DELETED.
• Sanção na conta dona. Suspensão ou banimento de quem criou o App desliga os Apps dele, com OWNER_SANCTIONED.
• Sanção no próprio App. A moderação da plataforma pode suspender ou banir um App: APP_SANCTIONED. A suspensão tem prazo e passa sozinha; o banimento também revoga as credenciais. Ela pode ainda revogar a credencial sem sancionar — aí o sinal é CREDENTIAL_REVOKED, o App continua instalado e o caminho é gerar outra credencial.

Em todos eles a conexão recebe um quadro de despedida com reconnect: false. Um cliente correto para de tentar e avisa quem o mantém — insistir seria bater numa porta que só um humano abre.

O resto da vida da credencial

O cabeçalho da versão que o SDK carimba em toda chamada, o que muda dentro de uma versão e o que exige versão nova estão em Versão da API e compatibilidade. Quem pode instalar o seu App, o link de instalação e o que a visibilidade decide são assunto do painel, em Criar e gerenciar um App.

O que NÃO existe

• Client secret e troca de código por token. Não há delegação de usuário: o App age sempre como ele mesmo.
• Redirect URI e tela de consentimento de usuário. Quem autoriza um App é quem administra o servidor, na tela de instalação.
• Um segredo de outro tipo. A segunda credencial da seção acima é uma vaga a mais da mesma coisa, e não um segredo com outro poder. A chave de assinatura das interações também não é sua: ela é da plataforma, é pública, e prova que o Trivo falou — o seu token prova que você falou.