Documentação · Chaves e tokens
Documentação
Chaves e tokens
Sessão do painel, token pessoal fgt_, chave pública stk_ e chave de servidor fgsk_: onde cada uma vale, como obter, rotacionar e revogar.
Conferido com o código e os pacotes publicados em 2026-10-16
Qual credencial usar
Há duas famílias. As chaves de projeto só enviam dados (ingestão) e identificam o projeto sozinhas. O token pessoal lê e altera dados em nome de uma pessoa, limitado pelas permissões que ela marcou e pelo papel dela em cada projeto.
| Credencial | Para quê | Como enviar | Onde obter |
|---|---|---|---|
fgsk_… chave de servidor | SDK Node, extensão Lambda, CLIs de release e source maps, crontab, curl de ingestão | Header x-fg-tracker-key. Nunca em URL. | Configurações → Geral → Chaves de ingestão (owner/admin) |
stk_… chave pública | fg-tracker-browser (erros, fetches e pageviews do navegador) | Header x-fg-tracker-key ou ?key= (o SDK usa ?key= no sendBeacon) | Mesmo card; é ela que vai no bundle do site |
fgt_… token pessoal | MCP, scripts, CI e leitura pela API | Authorization: Bearer fgt_… | Conta → Tokens de acesso → Novo token |
| Sessão do painel | Só o próprio painel | — | Não use em integrações |
Chave de servidor fgsk_
- Faz tudo o que uma chave de projeto pode fazer: spans de servidor, logs, check-ins, releases, source maps e agregados de infraestrutura.
- Só é aceita no header. Enviada em
?key=, a API responde401 SERVER_KEY_IN_URLe nada é gravado; como a URL pode ter ido para algum log, rotacione a chave. - Projetos novos já nascem com ela. Projetos antigos ganham uma em Gerar chave de servidor.
- Só owner e admin veem as chaves. Com token pessoal, a leitura exige a permissão
ingest_key:read.
Chave pública stk_
Feita para estar no bundle do site: qualquer pessoa que abre o site consegue lê-la. Por isso ela não dá acesso a leitura nenhuma, só a envio. Além da chave, o navegador precisa que a origem do site esteja em Configurações → Geral → Domínios permitidos (veja CORS).
Modo restrito da chave pública
Todo projeto começa no modo legado, em que a stk_ ainda aceita tudo o que a fgsk_ aceita (para não quebrar servidores antigos). Depois de trocar todos os servidores, CIs e funções para a fgsk_, clique em Restringir chave pública: a stk_ passa a enviar só eventos do navegador. O painel mostra o Último uso de servidor da chave pública para ajudar a achar quem ainda a usa.
| Envio | fgsk_ | stk_ legado | stk_ restrita |
|---|---|---|---|
Spans browser e http.client, pageviews | sim | sim | sim |
Spans http.server, db.query, custom | sim | sim | recusados um a um em 202 (public_key_not_allowed) |
Agregados de infra (infra[]) | sim | sim | recusados em infra.rejected |
| Logs, check-ins, releases, source maps | sim | sim | 403 PUBLIC_KEY_NOT_ALLOWED, nada gravado |
Para voltar ao legado, clique em Liberar chave pública. A troca vale na hora. Restringir exige que o projeto já tenha chave de servidor (sem ela, a API responde 409 SERVER_KEY_REQUIRED).
Token pessoal fgt_
Em Conta → Tokens de acesso → Novo token: escolha o nome, a validade (7, 30, 90 ou 180 dias, ou 1 ano; não há token sem validade), os projetos (todos em que você é membro ou alguns) e as permissões. O valor aparece uma vez, no diálogo Token criado. Para o MCP, o atalho Conectar → Usar MCP → Gerar token para o MCP abre o mesmo diálogo com o modelo certo.
- O token nunca faz mais do que o seu papel no projeto permite, e acompanha mudanças de papel e de projetos.
- Não expira com logout nem com troca de senha. Deixa de valer quando expira ou é revogado.
- Cada pessoa tem no máximo 20 tokens ativos.
- Conceder exclusão ou permissões de risco alto pede a sua senha (e o código do autenticador, se o MFA estiver ligado). Contas só com Google ou Meta precisam de MFA ativo para isso.
- Algumas operações nunca aceitam token, só a sessão do painel: criar e gerenciar tokens, senha, MFA, sessões, aceitar convites, WhatsApp, aprovar e aplicar mudanças na AWS.
Permissões do token
Cada permissão tem a forma recurso:operação. Criar, editar e excluir já incluem a leitura do mesmo recurso.
| Modelo | Permissões | Bom para |
|---|---|---|
| Somente leitura | projects:read, telemetry:read, issues:read, releases:read, monitors:read, alerts:read, infra:read, loadtest:read | painéis próprios, diagnóstico, MCP só leitura |
| Agente MCP (recomendado) | Somente leitura + members:read, projects:write, issues:write, releases:write, monitors:write, alerts:write | agente que cria projeto, faz triagem, registra release e cria monitores |
| Acesso total | todas | evite: inclui exclusões e mudanças na AWS |
Todas as permissões
| Recurso | Ler | Criar e editar | Excluir |
|---|---|---|---|
| Projetos e configurações | projects:read | projects:write | projects:delete |
| Chave de ingestão | ingest_key:read | ingest_key:write (rotacionar) | — |
| Telemetria (métricas, traces, logs) | telemetry:read | — | — |
| Issues | issues:read | issues:write | — |
| Releases | releases:read | releases:write | — |
| Source maps | sourcemaps:read | — | sourcemaps:delete |
| Monitores | monitors:read | monitors:write | monitors:delete |
| Alertas (criar e editar SLOs também usa alerts:write) | alerts:read | alerts:write | alerts:delete |
| Canais de alerta | alert_channels:read | alert_channels:write | alert_channels:delete |
| Membros | members:read | members:write | members:delete |
| IA | — | ai:use | — |
| Infraestrutura AWS | infra:read | infra:write | infra:delete |
| Mudanças na AWS | infra_changes:read | infra_changes:write | — |
| Testes de carga | loadtest:read | loadtest:write, loadtest:run | loadtest:delete |
| Credenciais de teste de carga | loadtest_credentials:read | loadtest_credentials:write | loadtest_credentials:delete |
Sessão do painel
O login do painel gera uma sessão de 14 dias guardada no navegador. Ela pode fazer tudo o que o seu papel permite, inclusive o que tokens não fazem. Não copie a sessão para scripts, CI ou MCP: ela não tem permissões limitadas, cai no logout e some do seu controle. Use um token pessoal.
Rotação e revogação
| Ação | Onde | Efeito |
|---|---|---|
Rotacionar fgsk_ | Chaves de ingestão → Rotacionar chave de servidor | A anterior para na hora, sem período de convivência. Troque servidores, CIs, crontabs e Lambdas antes ou logo depois. |
Rotacionar stk_ | Chaves de ingestão → Rotacionar chave pública | A anterior para na hora. Publique o site com a nova chave. A de servidor não muda. |
Revogar fgt_ | Conta → Tokens de acesso → Revogar | Para na hora: a próxima chamada recebe 401. Clientes MCP abertos precisam de um token novo. |
Editar permissões de fgt_ | Conta → Tokens de acesso → editar | Vale na próxima chamada. A validade não muda. O MCP só relê as permissões ao reiniciar. |
401 e 403
401 quer dizer que a credencial falta ou não vale (ausente, errada, expirada, revogada). 403 quer dizer que ela vale, mas não pode fazer aquilo. Os 403 trazem um code:
| code | Significado |
|---|---|
TOKEN_SCOPE_INSUFFICIENT | Falta a permissão em requiredScope. Com sessionOnly: true, a operação só existe no painel. |
PROJECT_ACCESS_DENIED | Você não é membro ativo do projeto (também para id inexistente). |
PROJECT_ROLE_INSUFFICIENT | Seu papel (viewer, por exemplo) não permite a operação. |
TOKEN_PROJECT_SCOPE | O token não vale para este projeto, ou é restrito a projetos e tentou criar um. |
PUBLIC_KEY_NOT_ALLOWED | stk_ restrita numa rota de servidor. |
EMAIL_VERIFICATION_REQUIRED | A conta ainda não confirmou o e-mail. |
Exemplos de corpo e a lista completa estão em API HTTP → Erros.