> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Espaços e chaves > Projeto, ambiente, fonte e chave: quem fala com a Niadra e o que cada chave pode fazer. 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: ```text theme={null} https://..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](/api/control/sources-create). 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`](/api/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: ```text theme={null} nia_sk_____ ``` * `live` chega aos espaços de produção; `test`, aos de sandbox. * `região` e `espaço` viram o endereço `https://..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. ```python Python theme={null} from niadra import Niadra niadra = Niadra() # lê NIADRA_API_KEY print(niadra.base_url) # https://acme-prod.us-east-1.api.niadra.com ``` ```typescript TypeScript theme={null} import { Niadra } from "@niadra/sdk"; const niadra = new Niadra(); // lê NIADRA_API_KEY ``` ```bash cURL theme={null} 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](/api/subject-tokens) 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](/api/insights-aggregate), 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](/conventions#autenticação). ## Girar e revogar [Gire](/api/control/keys-rotate) 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](/api/control/keys-revoke) ou [a fonte inteira](/api/control/source-revoke), 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`](/api/source-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 o que cada fonte envia e como o lote responde. handles, perfis e os níveis V0 a V4. versão, idempotência, limites de taxa e ETag. o catálogo de códigos, incluindo `scope_missing`.