Resumo: tudo o que liga o seu sistema ao nosso está em Configurações, API & MCP: você gera a credencial de API ali mesmo, cadastra webhooks e conecta o MCP. Não é mais preciso pedir credencial ao suporte.
Onde fica
Clique no logo da organização, no topo do menu lateral, e em API e MCP. Isso abre Configurações, aba API & MCP. A tela mostra, no topo, o endereço da API e o formato da autenticação, e em seguida três seções na ordem em que você precisa delas: credenciais, webhooks e MCP.Chaves de API
Gerar uma credencial
1
Configurações, API & MCP
Na seção Credenciais de API, clique em criar.
2
Dar um nome reconhecível
Use algo que você reconheça na hora de revogar:
backend-producao, n8n-homologacao, esteira-credito.3
Copiar o par
A tela mostra o
clientId e o clientSecret e só fecha quando você confirma que copiou.Revogar
A listagem mostra cada credencial com oclientId e a data de criação, e cada linha tem a ação de revogar. Revogar apaga a credencial dos dois lados: ela para de autenticar imediatamente.
Quantas você quiser
Uma por integração e por ambiente é o padrão saudável: dá para revogar a de homologação sem derrubar a produção.Quem pode
Quem tem a permissão gerenciar configurações (Administrador, Owner, Superuser). O mesmo perfil que cadastra webhook.Gerar token
OclientId + clientSecret são trocados por um token de acesso com validade de 24 horas. Seu backend precisa renovar o token antes de expirar.
O token é um JWT e carrega a claim
aud com o valor toolbox. Se o seu sistema lê as claims do token, espere esse valor. Fora isso, trate o token como opaco: use-o só no cabeçalho Authorization.Usar
Incluir o token em toda chamada HTTP:curl:
Webhooks
Permitem que a GYRA+ notifique seu backend quando algo relevante acontece (relatório concluído, política avaliada, exportação gerada, decisão manual de analista), em vez de você ficar fazendo polling. Você configura webhooks pela tela, na mesma aba API & MCP, ou pela API. Na tela você escolhe a URL, marca os eventos por categoria, testa o endereço com um disparo real e gira o segredo quando precisar. O catálogo de eventos vem do backend, então evento novo aparece ali sozinho.Existem duas famílias de eventos, e as duas aparecem na mesma lista:
- Relatórios e crédito, documentada nesta página e em Criar Webhook;
- Onboarding (cadastros e solicitações), com envelope e assinatura próprios, documentada em Eventos de webhook.
Tipos de evento
Cada webhook é registrado para um único tipo. Se você quer receber mais de um tipo, registre webhooks separados (mesma URL ou URLs diferentes).Configurar
type(obrigatório): um dos tipos da tabela acima.url(obrigatório): endpoint HTTPS que vai receber oPOST.apiKey(opcional): se informado, a GYRA+ envia esse valor no headerapi-keyde cada requisição, útil para o seu endpoint validar origem.
Estrutura do payload
Todo webhook entrega um POST com o formato:data varia por tipo:
REPORT_FINISHED
REPORT (seção individual concluída)
content.
REPORT_STATUS (decisão manual do analista)
REPORT_EXPORTED
exportUrl vem null e o payload inclui error.
CREDIT_POLICY
COMMITTEE_FINISHED (deliberação do comitê concluída)
GET /committee/deliberations/{reportId}, e a leitura combinada com os pareceres por seção em GET /report/{id}/insights. Se a deliberação falhar, status vem ERROR, decision não vem e o payload inclui error.
OPERATION
Retry
A GYRA+ faz até 3 tentativas de entrega com backoff exponencial (1s, ~2s, ~5s). Se o seu endpoint retornar429 com header Retry-After, a GYRA+ respeita o tempo antes de tentar de novo. Depois disso, o envio é descartado, planeje idempotência e fallback com polling em GET /v2/report/:id para eventuais perdas.
Boas práticas
- Responda 2xx rapidamente e processe o payload de forma assíncrona na sua fila interna.
- Use
externalIdnoPOST /v2/reportpara amarrar o webhook de volta ao seu pedido/cliente. - Escolha o tipo certo:
REPORT_FINISHEDpara a maioria dos fluxos (uma entrega por relatório),REPORTsó se você precisa reagir seção a seção. - Fallback com polling em
GET /v2/report/:idcaso o seu endpoint fique indisponível.
Conector de IA (MCP)
A terceira seção da tela liga o MCP da GYRA+ ao seu assistente. Ele não usa credencial de API: a autenticação é o seu próprio login da plataforma, com e-mail e senha ou Google. Ver Instalação do MCP.Restringir acesso via SSO-only
Por padrão, SSO (Google e Microsoft) convive com login por senha. Se você quer forçar SSO-only na sua organização, entre em contato comatendimento@gyramais.com para habilitar essa configuração.
Perguntas frequentes
Perdi meu clientSecret, como recupero?
Perdi meu clientSecret, como recupero?
Não tem como recuperar: guardamos só o hash. Crie uma credencial nova em Configurações, API & MCP e revogue a antiga.
Posso ter várias credenciais simultâneas?
Posso ter várias credenciais simultâneas?
Sim, e é o recomendado: uma por integração e por ambiente (dev, homologação, produção). Você cria quantas precisar pelo painel, sem pedir a ninguém.
Preciso pedir credencial ao suporte?
Preciso pedir credencial ao suporte?
Não. Desde setembro de 2026 a credencial é gerada por você mesmo em Configurações, API & MCP. O suporte segue disponível para dúvidas, mas não é mais o caminho para obter a chave.
Diferença entre webhook e polling?
Diferença entre webhook e polling?
Webhook é push (GYRA+ te avisa quando o relatório fica pronto). Polling é pull (você consulta
GET /v2/report/:id até concluir). Webhook é mais eficiente, mas exige endpoint público HTTPS.Como testar webhook em dev sem endpoint público?
Como testar webhook em dev sem endpoint público?
Use ferramentas como webhook.site para capturar o POST, ou ngrok para expor o seu localhost.
Próximos passos
Webhooks (conceito)
Como a GYRA+ emite eventos ao longo do ciclo de vida.
Como Funciona a API
Arquitetura geral dos endpoints.
MCP da GYRA+
Usar as credenciais via agente de IA.
Onboarding
O módulo documental, e os eventos que ele emite.

