Partes e aprovações

Um projeto da Niadra é operado por um tenant, mas os dados dele podem pertencer a outra empresa: a marca contrata uma consultoria que integra e opera os agentes; a rede de clínicas terceiriza o atendimento; a seguradora usa a plataforma de um parceiro. A lei chama uma de controladora e a outra de operadora, e a controladora precisa decidir o que se faz com os dados dela sem entrar no Console de quem opera. O modelo de contas dá nome a essas partes e leva cada decisão à controladora por um link, com um código no e-mail do encarregado dela. Esta página é sobre as pessoas jurídicas que respondem por um projeto. As organizações que são sujeitos da memória, clientes e parceiros com contexto próprio, estão em Contas e parceiros.

​

Onde isso vale

O modelo de contas não é uma funcionalidade de espaço: as rotas vivem na API de controle, com um token de pessoa do Console, e valem para todo tenant. Um projeto cuja controladora é o próprio tenant não muda em nada: nenhuma aprovação é pedida, e a revisão de acesso não vence. No Console, a tela Projeto e controlador, do papel security, e a tela Empresas aparecem quando o plano de controle serve o modelo de contas. Os links e os códigos saem por e-mail. Quando o e-mail não pode ser enviado, um pedido de aprovação responde 503 unavailable, e nenhum link fica valendo.

​

Entidades legais

Uma entidade legal (POST /v1/legal-entities) é uma empresa registrada uma vez por país e número de registro, com o nome e o e-mail do encarregado de proteção de dados. O número de registro fica como hash com chave e volta mascarado; o e-mail do encarregado fica lacrado e nunca volta: é para onde vão os links e os códigos. O mesmo número com o mesmo encarregado responde a entidade que já existe; com outro encarregado, 409. GET /v1/legal-entities lista as do tenant.

​

Partes de um projeto

Uma parte (POST /v1/projects/{project_id}/parties) liga uma entidade legal a um projeto com um papel: controller, operator ou sub_operator, e, se a parte usa o Console por um tenant, o id dele. O tenant que opera acrescenta a controladora dele; a partir daí, acrescentar uma operadora ou uma suboperadora ao projeto responde 409 controller_approval_required até a controladora aprovar add:<papel>:<id da entidade>, e encerrar uma operadora (POST .../parties/{party_id}/end) espera a aprovação de end:<id da parte>. GET /v1/projects/{project_id}/parties lista as partes, com desde quando e até quando.

​

Aprovações por link

Uma aprovação (POST /v1/approvals) é um pedido à controladora do projeto. A Niadra manda um link de uso único ao e-mail do encarregado dela, e a resposta da API nunca o traz. O pedido tem um tipo e um assunto: emergency_access é o oitavo tipo, e nunca é pedido: é como um acesso de emergência fica registrado. Cada aprovação tem document_hash, o SHA-256 do JSON canônico do que a controladora aprova, e um status: pending, approved, rejected ou expired. GET /v1/projects/{project_id}/approvals lista as de um projeto.

​

O link, passo a passo

A página de aprovação é pública, e o código do e-mail é a credencial dela. O token do link viaja só no corpo das requisições, nunca na URL de uma chamada à API.

1. POST /v1/approvals/link/preview mostra o que é pedido, por qual tenant, para qual projeto e até quando, antes de qualquer código. Um link desconhecido, já usado ou vencido responde 401 do mesmo jeito.
2. POST /v1/approvals/link/code manda um código de seis dígitos ao e-mail do encarregado, válido por 15 minutos: no máximo cinco códigos por link e um por minuto, senão 429.
3. POST /v1/approvals/link/open abre, com o código, o documento a decidir: o resumo e, num ripd, o relatório em Markdown. Um código errado é 401 e conta; o quinto erro fecha o link.
4. POST /v1/approvals/link/decide aprova ou recusa, uma vez, com uma nota opcional. O link para de valer, e a decisão vira um comprovante na corrente dos espaços do projeto.

​

O que espera a controladora

Num projeto cuja controladora não é o tenant, um diff de configuração que amplia finalidades, afrouxa a política ou estende uma retenção não vale ao ser aprovado no Console: ele espera a aprovação da controladora, pedida com o id do diff. O plano de controle confere isso quando o diff é enviado e de novo quando é aprovado. O mesmo vale para uma operadora que entra ou sai.

​

Transferência de operadora

Uma transferência (POST /v1/projects/{project_id}/transfer) passa a operação do projeto ao tenant de quem chama, com a aprovação transfer da controladora, cujo assunto é o id desse tenant. Os bancos dos espaços ficam onde estão, então a memória continua sem cópia. As chaves de fonte antigas continuam valendo por grace_hours (72 por padrão; 0 as corta na hora) e vencem em grace_until; a resposta diz quantas foram aposentadas e, por espaço, os endpoints de webhook cujos segredos o novo operador precisa trocar antes disso, porque um endpoint que ainda assina com um segredo antigo para de receber quando a carência acaba. Com operator_entity_id, a entidade legal do novo operador entra como operadora do projeto. GET /v1/projects/{project_id}/transfers lista as transferências.

​

Relatório de impacto

GET /v1/projects/{project_id}/ripd gera o relatório de impacto à proteção de dados a partir da configuração do espaço de produção, para uma finalidade: em Markdown e em JSON, com o SHA-256. O relatório é estável: a mesma configuração dá o mesmo documento e o mesmo hash. A controladora o aprova por link, como ripd com a finalidade como assunto, e approved_at diz quando ela aprovou este mesmo documento, pelo hash; uma configuração que mudou desde então volta sem approved_at.

​

Revisão de acesso

A cada 90 dias, a controladora confirma que o acesso das operadoras continua como está. GET /v1/projects/{project_id}/access-review diz quando ela aprovou pela última vez, quando a próxima revisão vence e se há um pedido pendente; o plano de controle pede a revisão sozinho quando ela vence. due_at é nulo num projeto sem controladora além do tenant.

​

Acesso de emergência

Um incidente às três da manhã não espera um link. POST /v1/projects/{project_id}/emergency-access dá a quem chama um papel (security, integration, review ou analysis) num espaço do projeto, na hora, por até quatro horas, com um motivo obrigatório. O próximo token da pessoa já leva o papel. A controladora é avisada por e-mail e pode encerrar o acesso pelo link; o acesso fica registrado como uma aprovação do tipo emergency_access, com o motivo, e como comprovante nos espaços.

​

Quem paga

PUT /v1/projects/{project_id}/payer nomeia o tenant que paga pelo projeto quando não é o que o opera; nulo volta ao tenant que opera. É uma rota da operação da Niadra, sob contrato, e payer_tenant_id aparece na leitura do projeto.

​

Comprovantes e privacidade

Toda decisão de uma aprovação, todo acesso de emergência e toda transferência entram na corrente de comprovantes dos espaços do projeto, e a controladora pode auditá-los pela própria cadeia. O e-mail do encarregado nunca sai lacrado; o registro da empresa nunca sai em claro; o token de um link nunca aparece numa URL da API nem num log.

​

Próximos passos