Operar o projeto de uma controladora

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.

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 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

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

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.

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:

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, e peça a aprovação com o id dele:

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:

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:

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:

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:

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}. 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 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

Partes e aprovações

o modelo por trás de cada passo.

Acesso ao Console

os papéis que cada rota pede.

Comprovantes e auditoria

onde cada decisão fica gravada.

Listar aprovações

a referência de GET /v1/projects/{project_id}/approvals.

Agentes

Por setor

Integrações

Operação

Operar o projeto de uma controladora

Antes de começar

1. Registre as duas empresas

2. Nomeie a controladora e a operadora

3. O que o encarregado vê

4. Diffs que esperam a controladora

5. O relatório de impacto

6. A revisão de acesso

7. Um incidente fora de hora

8. Passar a operação a outra empresa

O que fica registrado

Próximos passos

Partes e aprovações

Acesso ao Console

Comprovantes e auditoria

Listar aprovações

​Antes de começar

​1. Registre as duas empresas

​2. Nomeie a controladora e a operadora

​3. O que o encarregado vê

​4. Diffs que esperam a controladora

​5. O relatório de impacto

​6. A revisão de acesso

​7. Um incidente fora de hora

​8. Passar a operação a outra empresa

​O que fica registrado

​Próximos passos

Partes e aprovações

Acesso ao Console

Comprovantes e auditoria

Listar aprovações

Antes de começar

1. Registre as duas empresas

2. Nomeie a controladora e a operadora

3. O que o encarregado vê

4. Diffs que esperam a controladora

5. O relatório de impacto

6. A revisão de acesso

7. Um incidente fora de hora

8. Passar a operação a outra empresa

O que fica registrado

Próximos passos