# Protocolo Atlasberg

> Referência do protocolo da Atlasberg Platform: todos os headers x-atlasberg-* de request e response, métricas Prometheus atlasberg_* e o vocabulário de eventos da trilha de auditoria.

Todos os headers x-atlasberg-* definidos no código, as métricas Prometheus e o vocabulário de eventos da trilha de auditoria.

## Headers de request, camada Atlasberg

- Header: x-atlasberg-vk | O que faz: Chave virtual da requisição. Quando o chamador apresenta um token pessoal (prefixo atu-) em Authorization: Bearer, x-api-key, api-key ou x-goog-api-key, o gateway injeta aqui a chave virtual viva do time e remove o token dos headers.
- Header: x-atlasberg-app | O que faz: Nome de aplicação declarado pelo cliente para o inventário de agentes. A declaração vence a inferência, mas fica em campo próprio na trilha.
- Header: x-atlasberg-approver | O que faz: Quem decide uma aprovação quando não há sessão (auto-declarado).
- Header: x-atlasberg-idioma | O que faz: Idioma escolhido no console ou portal. Cascata: header, depois ATLASBERG_IDIOMA_PADRAO, depois Accept-Language.

## Headers de response, camada Atlasberg

- Header: x-atlasberg-dlp | O que faz: Contagem de dados pessoais mascarados no prompt, no formato categoria:n (por exemplo cpf:2,email:1). Só contagens, nunca conteúdo. Ausência do header significa nada mascarado.
- Header: X-Atlasberg-License | O que faz: Estado da licença (setup, valid, grace, expired) em toda resposta de gestão.

## Headers de request, motor de gateway

- Header: x-atlasberg-eh-<nome> | O que faz: Encaminha header arbitrário ao provedor (prefixo removido). Denylist impede sobrescrever auth como authorization, x-api-key e x-atlasberg-vk.
- Header: x-atlasberg-dim-<label> | O que faz: Dimensão custom nas métricas Prometheus (canônico).
- Header: x-atlasberg-prom-<label> | O que faz: Idem, depreciado; dim tem precedência.
- Header: x-atlasberg-session-id / x-atlasberg-session-ttl | O que faz: Stickiness de chave de provedor entre requests e TTL por request.
- Header: x-atlasberg-cache-key, -cache-ttl, -cache-type, -cache-threshold, -cache-no-store | O que faz: Controle do cache semântico por request.
- Header: x-atlasberg-async, -async-webhook, -async-id, -async-job-result-ttl | O que faz: Inferência assíncrona: criação, webhook, consulta, TTL do resultado.
- Header: x-atlasberg-compat | O que faz: Modo de compatibilidade por request.
- Header: x-atlasberg-disable-content-logging | O que faz: Desliga o log de conteúdo desta request.
- Header: x-atlasberg-send-back-raw-request / -send-back-raw-response / -store-raw-request-response | O que faz: Devolver ou armazenar o request e response crus do provedor.
- Header: x-atlasberg-passthrough-extra-params | O que faz: Repassa parâmetros extras ao provedor.
- Header: x-atlasberg-forwarded-proto | O que faz: Protocolo original atrás de proxy.
- Header: x-atlasberg-api-key | O que faz: Seleciona uma API key armazenada pelo nome (nunca o segredo cru).
- Header: x-atlasberg-direct-key | O que faz: Opt-in por request de chave direta de provedor (exige opt-in do admin).
- Header: x-atlasberg-mcp-session-id, -mcp-include-tools, -mcp-include-clients | O que faz: Sessão e filtros MCP.
- Header: x-atlasberg-prompt-id / x-atlasberg-prompt-version | O que faz: Seleção de prompt gerenciado.
- Header: x-atlasberg-customer-id / x-atlasberg-customer-name | O que faz: Escopo de customer num caminho de chave virtual de time (governança enterprise).
- Header: x-atlasberg-lh-<label> | O que faz: Metadados para o exportador de logging (tenant, user, tag, shared).
- Header: x-atlasberg-maxim-<label> | O que faz: Metadados de tracing do exportador maxim.
- Header: x-atlasberg-event | O que faz: Header de evento nos webhooks de saída.

## Headers de response, motor de gateway

Nota de correlação: O header de correlação é x-request-id. O gateway não escreve um header x-atlasberg-request-id.

- Header: x-atlasberg-provider, -original-model, -resolved-model, -fallback-index, -request-type, -upstream-latency-ms | O que faz: Identidade roteada da resposta: provedor e modelo reais, fallback, latência upstream acumulada em ms.
- Header: x-atlasberg-routing-info-* (provider, model, key, alias-model-id/name/family, is-fallback, primary-provider, primary-model, server-side-fallback-model) | O que faz: Espelho 1:1 do RoutingInfo não depreciado.
- Header: x-atlasberg-trace-id | O que faz: Id de trace na resposta.

## Métricas Prometheus

Scrape em GET /metrics; também há suporte a push gateway. Labels custom por request via x-atlasberg-dim-*. Existe também um plugin OTel no motor.

- Métrica: atlasberg_upstream_requests_total | Tipo: counter
- Métrica: atlasberg_upstream_latency_seconds | Tipo: histograma
- Métrica: atlasberg_success_requests_total | Tipo: counter
- Métrica: atlasberg_error_requests_total | Tipo: counter
- Métrica: atlasberg_input_tokens_total / atlasberg_output_tokens_total | Tipo: counter
- Métrica: atlasberg_cache_hits_total | Tipo: counter
- Métrica: atlasberg_cache_read_input_tokens_total, atlasberg_cache_write_input_tokens_total, _5m_total, _1h_total | Tipo: counter
- Métrica: atlasberg_cost_total | Tipo: counter
- Métrica: atlasberg_stream_inter_token_latency_seconds, atlasberg_stream_first_token_latency_seconds | Tipo: histograma
- Métrica: atlasberg_request_retries | Tipo: counter
- Métrica: atlasberg_key_rotation_events_total | Tipo: counter
- Métrica: atlasberg_active_requests | Tipo: gauge
- Métrica: atlasberg_provider_key_up | Tipo: gauge
- Métrica: atlasberg_mcp_client_operation_duration_seconds | Tipo: histograma

## Vocabulário de eventos da trilha

A trilha é encadeada por hash e assinada. Arquivos no diretório da aplicação: atlasberg-audit.log (eventos), atlasberg-audit-anchors.log (âncoras assinadas Ed25519) e atlasberg-deployment-key.json (chave do deployment, gerada no primeiro boot). Dois outros arquivos moram ao lado: atlasberg-console-sessions.json (modo 0600; o SHA-256 de cada token de sessão do console, o sujeito e a expiração) e atlasberg-tokens-pessoais.json (modo 0600; digests SHA-256 dos tokens pessoais, realocável com ATLASBERG_TOKENS_PESSOAIS_DIR). Um gateway sem trilha não sobe. A chave pública do deployment é impressa no log de boot para o auditor.

- Evento: llm.admission | Significado: Uma requisição LLM foi admitida.
- Evento: dlp.verdict | Significado: Veredito de DLP.
- Evento: file.verdict | Significado: Veredito de arquivo.
- Evento: llm.metrics | Significado: Exatamente um por request (não por chunk de stream): provedor, modelo, tokens, latência, status e hash pseudonimizado da resposta inteira.
- Evento: llm.coverage | Significado: Cobertura.
- Evento: llm.sanitization | Significado: Sanitização.
- Evento: budget.degraded | Significado: Um orçamento suave serviu no modelo mais barato.
- Evento: budget.degrade_blocked | Significado: A reescrita foi impedida.
- Evento: approval.parked | decided | expired | used | returned | refused | Significado: Ciclo de vida de aprovação.
- Evento: config.change / policy.change | Significado: Mudanças de configuração e de política.
- Evento: auth.login / auth.logout / auth.refused / auth.refused_burst | Significado: Eventos de autenticação; o evento de burst agrega recusas por origem.
- Evento: auth.device.started / auth.device.approved / auth.device.denied | Significado: Login por dispositivo: um terminal pediu um código (o ator é o sujeito não autenticado e a origem vai no detalhe), uma pessoa aprovou ou negou.
- Evento: auth.token.issued / auth.token.revoked | Significado: Ciclo de vida do token pessoal. Motivos de revogação: pessoa (o próprio dono), administrador, teto (deslocado pelo teto por pessoa), logout, diretorio (pessoa desligada no diretório). Inferência com token não é evento próprio; é o caminho comum da requisição, coberto pelos eventos llm.*.
- Evento: license.import | Significado: Cada tentativa de import de licença, aceita ou recusada.
- Evento: virtualkey.created / virtualkey.revoked | Significado: Ciclo de vida de chave virtual.
- Evento: audit.anchored / audit.exported / audit.pruned | Significado: Operações da trilha.
- Evento: gateway.started | Significado: Boot.
- Evento: clock.retrograde | Significado: O relógio retrocedeu.
- Evento: admin.request | Significado: Requisição administrativa.
- Conteúdo nunca entra na trilha: hashes de prompt e resposta usam um pepper de 32 bytes gerado no primeiro boot e guardado no arquivo de chave do deployment. À parte, o pepper de pseudonimização do DLP no arquivo de política recusa o placeholder de fábrica.
- Digests que carregam prefixo de credencial (sk-atlas-, sk-ant-, sk-proj-, sk-or-) são bloqueados na trilha.
- O ator de um evento de inferência é o digest da chave virtual, ou anonimo. O ator de eventos administrativos é o que a autenticação resolveu, nunca um header do chamador: local:<usuario> para sessão do console aberta por conta de local_login com o grupo de console, o sujeito genérico sessao de administracao para o par de admin break-glass, e sincronizacao_diretorio para os ciclos de sincronização com o diretório.
- Perfis de retenção: ATLASBERG_AUDIT_PROFILE=bancario liga âncoras horárias e retenção de cinco anos (Res. CMN 4.893, art. 23). ATLASBERG_AUDIT_RETENTION_DAYS não baixa o piso do perfil bancário.
- Poda destrutiva de retenção roda offline com a ferramenta atlasberg-prune, em dois passos, com âncora testemunha guardada fora do gateway.

## Sobre a Atlasberg Platform

A Atlasberg Platform é a camada de controle entre uma empresa e todos os modelos de IA: cada requisição é autenticada com uma chave virtual, filtrada por política e DLP, roteada para o provedor certo e gravada numa trilha de auditoria encadeada por hash. Expõe uma API compatível com a OpenAI, então as aplicações só trocam a URL base.

O mesmo artefato roda na Atlasberg Cloud, na sua VPC, on-premises ou totalmente air-gapped, e é cobrado por capacidade e módulos, nunca por assento.

Esta página faz parte da documentação oficial. Para falar com o time de engenharia, escreva para contact@atlasberg.com ou use https://atlasberg.com/pt-br/contato. A resposta vem em até um dia útil.

## Mais da Atlasberg

- [Índice da documentação](https://atlasberg.com/pt-br/docs)
- [Visão geral da plataforma](https://atlasberg.com/pt-br)
- [Fale com a engenharia](https://atlasberg.com/pt-br/contato)

---
Fonte: https://atlasberg.com/pt-br/docs/protocolo
Empresa: Sobimann Tecnologia da Informacao LTDA (Atlasberg), Porto Alegre, RS, Brasil.
Contato: contact@atlasberg.com - resposta em até um dia útil.
Índice para agentes: https://atlasberg.com/llms.txt