Espaços e chaves

Tudo o que fala com a Niadra fala por uma chave, e toda chave pertence a uma fonte dentro de um espaço. Esses três nomes decidem onde o dado mora, quem está lendo e o que cada agente pode fazer com a memória. Entender os três antes de integrar evita a maior parte das dúvidas de permissão.

Projeto, ambiente e espaço

Um projeto é a memória de uma empresa, ou de uma linha de negócio que precisa ficar separada. Cada projeto tem dois ambientes: sandbox, para desenvolver e testar, e production, para o tráfego real. O espaço é o par projeto e ambiente. É a unidade de isolamento da Niadra: o espaço é a primeira coluna de toda chave de banco, de cache e de cifra, então um evento de sandbox nunca aparece numa leitura de produção, e o dado de uma empresa nunca decifra com a chave de outra. Cada espaço vive numa região, a do projeto, e tem um endereço estável:

https://<espaço>.<região>.api.niadra.com

O SDK monta esse endereço a partir da chave. Você não configura URL nenhuma, a não ser para apontar para o emulador local.

Fontes

Uma fonte é cada coisa que fala com a memória: o agente de voz de um fornecedor, o agente de WhatsApp de outro, o agente interno de cobrança, o CRM que manda eventos por webhook, o atendente humano que recebe o contexto na ferramenta que a empresa já usa. Toda fonte tem:

Atributo	Para quê
`purposes`	O que ela lê e para quê, como `customer_service` ou `billing`. A política libera cada categoria de memória por finalidade.
`audience`	`customer_agent`, `internal_agent`, `human`, `reviewer`, `analyst`, `trigger_target` ou `export`. Decide o que a fonte pode ler, define os escopos padrão das chaves dela e aparece em todo comprovante.
`vendor` e `channel`	Quem fez o agente e onde ele trabalha. A medição agrupa por eles.
`verification_ceiling`	O nível mais alto que a fonte pode declarar, V2 por padrão. Agente automatizado: V2. Fonte que executa OTP: V3. V4 só para mesa humana ou sistema de registro.
`confirms_before_acting`	Marca o agente que confirma valores por regra de prompt, para a medição não contar essa confirmação como repetição.
`navigation_enabled`	Se a fonte pode usar as ferramentas do histórico. Ligado por padrão.
`trusted_action_ops`	Com `act`, a lista fechada de operações que a fonte pode registrar, como `credit`. Vazia quer dizer qualquer operação.
`critical`	Deixa a fonte fora dos grupos de controle de experimento: os clientes dela sempre recebem a memória.

A fonte é criada e configurada no Console ou pela API de controle. Acesso à memória é negado por padrão e liberado por finalidade: dar acesso amplo ao ERP para um agente interno não dá acesso amplo à memória. Antes de liberar, POST /v1/policy/simulate mostra o que uma fonte, audiência ou finalidade veria de um perfil, item a item, com o que ficaria retido e por quê.

Chaves

Cada fonte tem uma ou mais chaves. O formato carrega tudo o que o SDK precisa para achar o endereço:

nia_sk_<live|test>_<região>_<espaço>_<key_id>_<segredo>

live chega aos espaços de produção; test, aos de sandbox.
região e espaço viram o endereço https://<espaço>.<região>.api.niadra.com.
key_id é público e aparece nos registros; sozinho, nunca autentica.
O segredo aparece uma vez só, quando a chave é criada. Guarde no seu cofre de segredos.

A chave vai no cabeçalho Authorization: Bearer. Os SDKs leem a variável NIADRA_API_KEY quando você não passa a chave no construtor.

from niadra import Niadra

niadra = Niadra()  # lê NIADRA_API_KEY
print(niadra.base_url)  # https://acme-prod.us-east-1.api.niadra.com

import { Niadra } from "@niadra/sdk";

const niadra = new Niadra(); // lê NIADRA_API_KEY

curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/context" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"type": "phone_e164", "value": "+14155550123"}, "view": "chat"}'

A chave de fonte é segredo de servidor. Nunca coloque uma chave no navegador, num app móvel ou no prompt do modelo. Para ligar um cliente a uma conexão MCP, o seu backend emite um subject_token de 15 minutos.

Escopos

Cada chave tem escopos. A rota confere o escopo antes de qualquer outra coisa, e a falta dele volta como 403 com o código scope_missing.

Escopo	O que libera
`track`	Enviar mensagens e eventos de sistema no lote, pedir upload de mídia, corrigir a memória
`act`	Registrar ação de agente, dentro das `trusted_action_ops` da fonte quando ela tem lista
`context`	Ler o contexto e objetos, emitir `subject_token`
`search`	Buscar no histórico, linha do tempo, abrir item
`identify`	Mandar itens `identify` no lote; a ferramenta MCP `resolve_identity`
`admin`	Toda rota de governança: identidade, apagamento, exportação, comprovantes, linhagem, simulação de política, medição, gatilhos, entregas. As mesmas rotas aceitam também pessoas do Console com o papel certo
`analytics`	Análise da base, com pseudônimo por padrão. Só fontes com a audiência `analyst` recebem

O escopo act merece atenção. track sozinho não registra ação: uma ação pode fechar uma promessa feita ao cliente, então só a fonte com act consegue registrá-la, e a fonte que declara trusted_action_ops (por exemplo, só credit) não registra mais nada. É a primeira barreira contra uma ação forjada por injeção de prompt. Uma operação fora da lista volta como erro do item, com o código operation_not_allowed. Uma chave criada sem escopos recebe os padrões da audiência da fonte: customer_agent recebe track, context, search e identify; internal_agent recebe também act; human recebe context e search; analyst recebe só analytics. Uma divisão comum:

Fonte	Escopos
Agente de voz ou de WhatsApp	`context`, `search`, `track`, `identify`
Agente interno de cobrança	`context`, `search`, `track`, `act`, com `trusted_action_ops: ["credit"]` na fonte
CRM ou ERP por webhook	autenticação do mapeamento da fonte
Serviço de governança do seu time	`admin`
Seu BI ou LLM de análise	`analytics`, numa fonte com a audiência `analyst`

As pessoas do seu time usam o Console com o próprio token e os próprios papéis (admin, security, integration, review, analysis, vendor), nunca uma chave de fonte. Veja Limites e convenções.

Girar e revogar

Gire uma chave para ganhar uma nova com os mesmos escopos; grace_seconds (até 7 dias) mantém a antiga válida enquanto você publica a nova no seu cofre. Para cortar o acesso, revogue a chave ou a fonte inteira, com um motivo, no Console ou pela API de controle. A revogação chega a todas as instâncias da célula em segundos. A célula também aceita um corte direto, POST /v1/sources/{source_id}/revoke, para o papel security: todas as chaves da fonte param de autenticar ali na hora. Quando uma chave recebe 401 ou 403, o SDK descarta o contexto que tinha guardado para ela e devolve contexto vazio. Assim o corte de acesso de um fornecedor vale também para o que já estava no cache dele.

Próximos passos

Eventos e o lote

o que cada fonte envia e como o lote responde.

Identidade e verificação

handles, perfis e os níveis V0 a V4.

Limites e convenções

versão, idempotência, limites de taxa e ETag.

Erros

o catálogo de códigos, incluindo scope_missing.

A base da memória

O que o agente recebe

Governança

Espaços e chaves

Projeto, ambiente e espaço

Fontes

Chaves

Escopos

Girar e revogar

Próximos passos

Eventos e o lote

Identidade e verificação

Limites e convenções

Erros

​Projeto, ambiente e espaço

​Fontes

​Chaves

​Escopos

​Girar e revogar

​Próximos passos

Eventos e o lote

Identidade e verificação

Limites e convenções

Erros

Projeto, ambiente e espaço

Fontes

Chaves

Escopos

Girar e revogar

Próximos passos