> ## 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. # Operar o projeto de uma controladora > Registre as duas empresas, nomeie a controladora do projeto, leve a ela por link o que precisa de aprovação e mantenha a revisão de acesso em dia. A sua empresa integra e opera os agentes de um cliente, e os dados são dele. Este guia monta o projeto do jeito que a lei espera: a controladora nomeada, as decisões dela tomadas por um link com um código no e-mail do encarregado, e o acesso da sua empresa revisado a cada 90 dias. Os conceitos estão em [Partes e aprovações](/concepts/approvals). ## Antes de começar * Um token de pessoa do Console do seu tenant, com o papel `admin` para as entidades e as partes e `security` para os diffs de configuração. Nos exemplos, `NIADRA_TOKEN`, contra a [API de controle](/api#autenticação) em `https://control.api.niadra.com`. * O id do projeto (`PROJECT_ID`) e, para os diffs, o id do espaço de produção (`SPACE_ID`). * O nome, o país, o número de registro e o e-mail do encarregado de proteção de dados das duas empresas: a sua e a do cliente. O e-mail do encarregado do cliente é para onde os links vão; confirme com ele antes. ## 1. Registre as duas empresas ```sh theme={null} curl -X POST "https://control.api.niadra.com/v1/legal-entities" \ -H "Authorization: Bearer $NIADRA_TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Rede Aurora Saúde", "country": "BR", "registry": "12345678000190", "dpo_email": "encarregado@aurora.example"}' ``` A resposta traz `entity_id`, o registro mascarado e nunca o e-mail. Registre a sua empresa do mesmo jeito. Uma segunda chamada com o mesmo registro e o mesmo e-mail responde a entidade que já existe; com outro e-mail, 409, porque o encarregado de uma empresa não muda por uma requisição. ## 2. Nomeie a controladora e a operadora ```sh theme={null} curl -X POST "https://control.api.niadra.com/v1/projects/$PROJECT_ID/parties" \ -H "Authorization: Bearer $NIADRA_TOKEN" -H "Content-Type: application/json" \ -d '{"entity_id": "'$CONTROLLER_ENTITY'", "role": "controller"}' ``` Com a controladora nomeada, o projeto passa a esperar por ela. Acrescentar a sua empresa como operadora agora responde 409 `controller_approval_required`: peça a aprovação e repita a chamada depois que ela aprovar. ```sh theme={null} curl -X POST "https://control.api.niadra.com/v1/approvals" \ -H "Authorization: Bearer $NIADRA_TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \ -d '{"project_id": "'$PROJECT_ID'", "kind": "operators", "subject_ref": "add:operator:'$OPERATOR_ENTITY'"}' ``` A resposta é a aprovação, `pending`, com `approval_id`, `document_hash` e `expires_at`. O link foi ao e-mail do encarregado da controladora e não vem na resposta. ## 3. O que o encarregado vê O link abre a página pública de aprovação do Console. Ela mostra o que é pedido, por qual tenant e para qual projeto; o encarregado pede o código, recebe seis dígitos no mesmo e-mail, abre o documento e decide. Cinco códigos por link, um por minuto; cinco códigos errados fecham o link, e um link vencido ou usado responde igual a um que nunca existiu. A decisão vale uma vez e vira um comprovante nos espaços do projeto. Acompanhe pela API: ```sh theme={null} curl "https://control.api.niadra.com/v1/projects/$PROJECT_ID/approvals" -H "Authorization: Bearer $NIADRA_TOKEN" ``` Quando o status é `approved`, repita o passo 2 para a operadora. Uma aprovação `expired` pede um pedido novo. ## 4. Diffs que esperam a controladora Um diff de configuração que amplia as finalidades do espaço, afrouxa a política de acesso ou estende uma retenção não vale ao ser aprovado no seu Console: ele fica pendente até a controladora aprovar. Envie o diff como sempre, pela tela Configuração ou por [`POST /v1/config/diffs`](/api/control/config-diffs), e peça a aprovação com o id dele: ```sh theme={null} curl -X POST "https://control.api.niadra.com/v1/approvals" \ -H "Authorization: Bearer $NIADRA_TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \ -d '{"project_id": "'$PROJECT_ID'", "kind": "purposes", "subject_ref": "'$DIFF_ID'"}' ``` Os outros diffs, os que restringem ou só mudam a operação, valem como sempre. O plano de controle confere isso quando o diff é enviado e de novo quando é aprovado. ## 5. O relatório de impacto Gere o relatório para cada finalidade do espaço e peça a aprovação dele. Como o relatório é estável, a controladora aprova um hash, e a leitura diz quando ela aprovou este mesmo documento: ```sh theme={null} curl "https://control.api.niadra.com/v1/projects/$PROJECT_ID/ripd?purpose=customer_service" -H "Authorization: Bearer $NIADRA_TOKEN" # -> { "purpose": "customer_service", "sha256": "...", "markdown": "...", "document": {...}, "approved_at": null } curl -X POST "https://control.api.niadra.com/v1/approvals" \ -H "Authorization: Bearer $NIADRA_TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \ -d '{"project_id": "'$PROJECT_ID'", "kind": "ripd", "subject_ref": "customer_service"}' ``` Uma configuração que mudou depois gera outro documento, com outro hash, sem `approved_at`: peça de novo. ## 6. A revisão de acesso A cada 90 dias, a controladora confirma que o acesso da sua empresa continua como está. O plano de controle pede a revisão sozinho quando ela vence; você acompanha em: ```sh theme={null} curl "https://control.api.niadra.com/v1/projects/$PROJECT_ID/access-review" -H "Authorization: Bearer $NIADRA_TOKEN" # -> { "last_approved_at": "2026-07-01T12:00:00Z", "due_at": "2026-09-29T12:00:00Z", "pending": null } ``` ## 7. Um incidente fora de hora Quando alguém precisa de um papel que não tem, agora, sem esperar um link: ```sh theme={null} curl -X POST "https://control.api.niadra.com/v1/projects/$PROJECT_ID/emergency-access" \ -H "Authorization: Bearer $NIADRA_TOKEN" -H "Content-Type: application/json" \ -d '{"space_id": "'$SPACE_ID'", "role": "security", "minutes": 120, "reason": "webhook secret leaked in a build log; rotating"}' ``` O papel vale no próximo token, por até quatro horas. A controladora é avisada por e-mail e pode encerrar o acesso pelo link, e ele fica registrado como uma aprovação do tipo `emergency_access`, com o motivo. ## 8. Passar a operação a outra empresa Quando o cliente troca de operadora, é a operadora nova que pede a transferência, depois de a controladora aprovar `transfer` com o id do tenant dela como assunto: ```sh theme={null} curl -X POST "https://control.api.niadra.com/v1/projects/$PROJECT_ID/transfer" \ -H "Authorization: Bearer $NEW_OPERATOR_TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \ -d '{"to_tenant_id": "'$NEW_TENANT'", "approval_id": "'$APPROVAL_ID'", "grace_hours": 72, "operator_entity_id": "'$NEW_OPERATOR_ENTITY'"}' ``` Os bancos dos espaços ficam onde estão: a memória dos clientes continua. As suas chaves de fonte continuam valendo por 72 horas e vencem em `grace_until`; a resposta lista, por espaço, os endpoints de webhook cujos segredos a operadora nova precisa trocar antes disso, com [`PUT /v1/secrets/webhook/{id}`](/api/secrets). Um endpoint que ainda assina com um segredo seu para de receber quando a carência acaba. ## O que fica registrado Cada decisão, cada acesso de emergência e cada transferência entram na [corrente de comprovantes](/concepts/receipts) dos espaços do projeto, que a controladora pode auditar pela própria cadeia. No Console, a tela Projeto e controlador, do papel `security`, mostra as partes, as aprovações pendentes e decididas, a revisão de acesso e as transferências, e a tela Empresas mostra as entidades legais do tenant. ## Próximos passos o modelo por trás de cada passo. os papéis que cada rota pede. onde cada decisão fica gravada. a referência de `GET /v1/projects/{project_id}/approvals`.