Atlasberg protocol

Request headers, Atlasberg layer

• Header: x-atlasberg-vk | What it does: The request's virtual key. When the caller presents a personal token (prefix atu-) in Authorization: Bearer, x-api-key, api-key or x-goog-api-key, the gateway injects the team's live virtual key here and removes the token from the headers.
• Header: x-atlasberg-app | What it does: Application name declared by the client for the agent inventory. The declaration wins over inference but stays in its own field in the trail.
• Header: x-atlasberg-approver | What it does: Who decides an approval when there is no session (self-declared).
• Header: x-atlasberg-idioma | What it does: Language chosen in console or portal. Cascade: header, then ATLASBERG_IDIOMA_PADRAO, then Accept-Language.

Response headers, Atlasberg layer

• Header: x-atlasberg-dlp | What it does: Count of personal data masked in the prompt, in categoria:n format (for example cpf:2,email:1). Counts only, never content. Absence means nothing was masked.
• Header: X-Atlasberg-License | What it does: License state (setup, valid, grace, expired) on every management response.

Request headers, gateway engine

• Header: x-atlasberg-eh-<name> | What it does: Forwards an arbitrary header to the provider (prefix stripped). A denylist prevents overriding auth headers such as authorization, x-api-key and x-atlasberg-vk.
• Header: x-atlasberg-dim-<label> | What it does: Custom dimension on the Prometheus metrics (canonical).
• Header: x-atlasberg-prom-<label> | What it does: Same as dim, deprecated; dim takes precedence.
• Header: x-atlasberg-session-id / x-atlasberg-session-ttl | What it does: Provider key stickiness across requests, and per-request TTL.
• Header: x-atlasberg-cache-key, -cache-ttl, -cache-type, -cache-threshold, -cache-no-store | What it does: Per-request semantic cache control.
• Header: x-atlasberg-async, -async-webhook, -async-id, -async-job-result-ttl | What it does: Async inference: creation, webhook, lookup, result TTL.
• Header: x-atlasberg-compat | What it does: Per-request compatibility mode.
• Header: x-atlasberg-disable-content-logging | What it does: Turns off content logging for this request.
• Header: x-atlasberg-send-back-raw-request / -send-back-raw-response / -store-raw-request-response | What it does: Return or store the raw provider request and response.
• Header: x-atlasberg-passthrough-extra-params | What it does: Passes extra parameters through to the provider.
• Header: x-atlasberg-forwarded-proto | What it does: Original protocol behind a proxy.
• Header: x-atlasberg-api-key | What it does: Selects a stored API key by name (never the raw secret).
• Header: x-atlasberg-direct-key | What it does: Per-request opt-in to a direct provider key (requires admin opt-in).
• Header: x-atlasberg-mcp-session-id, -mcp-include-tools, -mcp-include-clients | What it does: MCP session and filters.
• Header: x-atlasberg-prompt-id / x-atlasberg-prompt-version | What it does: Managed prompt selection.
• Header: x-atlasberg-customer-id / x-atlasberg-customer-name | What it does: Customer scope on a team virtual key path (enterprise governance).
• Header: x-atlasberg-lh-<label> | What it does: Metadata for the logging exporter (tenant, user, tag, shared).
• Header: x-atlasberg-maxim-<label> | What it does: Tracing metadata for the maxim exporter.
• Header: x-atlasberg-event | What it does: Event header on outgoing webhooks.

Response headers, gateway engine

Correlation note: The correlation header is x-request-id. The gateway does not write an x-atlasberg-request-id header.

• Header: x-atlasberg-provider, -original-model, -resolved-model, -fallback-index, -request-type, -upstream-latency-ms | What it does: Routed identity of the response: real provider and model, fallback, accumulated upstream latency in ms.
• Header: x-atlasberg-routing-info-* (provider, model, key, alias-model-id/name/family, is-fallback, primary-provider, primary-model, server-side-fallback-model) | What it does: A one-to-one mirror of the non-deprecated RoutingInfo.
• Header: x-atlasberg-trace-id | What it does: Trace id on the response.

Prometheus metrics

Scrape at GET /metrics; push gateway support also exists. Custom labels per request via x-atlasberg-dim-*. An OTel plugin also exists in the engine.

• Metric: atlasberg_upstream_requests_total | Type: counter
• Metric: atlasberg_upstream_latency_seconds | Type: histogram
• Metric: atlasberg_success_requests_total | Type: counter
• Metric: atlasberg_error_requests_total | Type: counter
• Metric: atlasberg_input_tokens_total / atlasberg_output_tokens_total | Type: counter
• Metric: atlasberg_cache_hits_total | Type: counter
• Metric: atlasberg_cache_read_input_tokens_total, atlasberg_cache_write_input_tokens_total, _5m_total, _1h_total | Type: counter
• Metric: atlasberg_cost_total | Type: counter
• Metric: atlasberg_stream_inter_token_latency_seconds, atlasberg_stream_first_token_latency_seconds | Type: histogram
• Metric: atlasberg_request_retries | Type: counter
• Metric: atlasberg_key_rotation_events_total | Type: counter
• Metric: atlasberg_active_requests | Type: gauge
• Metric: atlasberg_provider_key_up | Type: gauge
• Metric: atlasberg_mcp_client_operation_duration_seconds | Type: histogram

Audit trail event vocabulary

The trail is hash-chained and signed. Files in the application directory: atlasberg-audit.log (events), atlasberg-audit-anchors.log (Ed25519 signed anchors) and atlasberg-deployment-key.json (deployment key, generated on first boot). Two more files live next to them: atlasberg-console-sessions.json (mode 0600; the SHA-256 of each console session token, its subject and expiry) and atlasberg-tokens-pessoais.json (mode 0600; SHA-256 digests of personal tokens, relocatable with ATLASBERG_TOKENS_PESSOAIS_DIR). A gateway without a trail does not boot. The deployment public key is printed in the boot log for the auditor.

• Event: llm.admission | Meaning: An LLM request was admitted.
• Event: dlp.verdict | Meaning: DLP verdict.
• Event: file.verdict | Meaning: File verdict.
• Event: llm.metrics | Meaning: Exactly one per request (not per stream chunk): provider, model, tokens, latency, status and a pseudonymized hash of the entire response.
• Event: llm.coverage | Meaning: Coverage.
• Event: llm.sanitization | Meaning: Sanitization.
• Event: budget.degraded | Meaning: A soft budget served on the cheaper model.
• Event: budget.degrade_blocked | Meaning: The rewrite was blocked.
• Event: approval.parked | decided | expired | used | returned | refused | Meaning: Approval lifecycle.
• Event: config.change / policy.change | Meaning: Configuration and policy changes.
• Event: auth.login / auth.logout / auth.refused / auth.refused_burst | Meaning: Authentication events; the burst event aggregates refusals per origin.
• Event: auth.device.started / auth.device.approved / auth.device.denied | Meaning: Device login: a terminal asked for a code (the actor is the unauthenticated subject and the origin is in the details), a person approved or denied it.
• Event: auth.token.issued / auth.token.revoked | Meaning: Personal token lifecycle. Revocation reasons: pessoa (the owner), administrador, teto (displaced by the per-person ceiling), logout, diretorio (person disabled in the directory). Inference with a token is not an event of its own; it is the ordinary request path covered by llm.* events.
• Event: license.import | Meaning: Every license import attempt, accepted or refused.
• Event: virtualkey.created / virtualkey.revoked | Meaning: Virtual key lifecycle.
• Event: audit.anchored / audit.exported / audit.pruned | Meaning: Trail operations.
• Event: gateway.started | Meaning: Boot.
• Event: clock.retrograde | Meaning: The clock moved backwards.
• Event: admin.request | Meaning: Administrative request.
• Content never enters the trail: prompt and response hashes use a 32 byte pepper generated on first boot and stored in the deployment key file. Separately, the DLP pseudonymization pepper in the policy file refuses the factory placeholder.
• Digests carrying a credential prefix (sk-atlas-, sk-ant-, sk-proj-, sk-or-) are blocked from the trail.
• The actor of an inference event is the digest of the virtual key, or anonimo. The actor of administrative events is what authentication resolved, never a caller header: local:<username> for a console session opened by a local_login account with the console group, the generic administration session subject for the break-glass admin pair, and sincronizacao_diretorio for directory synchronization cycles.
• Retention profiles: ATLASBERG_AUDIT_PROFILE=bancario turns on hourly anchors and five year retention (CMN Resolution 4.893, article 23). ATLASBERG_AUDIT_RETENTION_DAYS cannot go below the banking floor.
• Destructive retention pruning runs offline with the atlasberg-prune tool, in two steps, with a witness anchor stored outside the gateway.

About Atlasberg Platform

Atlasberg Platform is the control layer between a company and every AI model: each request is authenticated with a virtual key, filtered by policy and DLP, routed to the right provider and written to a hash-chained audit trail. It exposes an OpenAI-compatible API, so applications only swap the base URL.

The same artifact runs in Atlasberg Cloud, in your VPC, on-premises or fully air-gapped, and is priced by capacity and modules, never per seat.

This page is part of the official documentation. To talk to the engineering team, write to [email protected] or use https://atlasberg.com/contato. Answers come within one business day.