Uso da API

Uso da API

Tudo o que a tela do IAM faz está na Public API da NNumbers Console, sob o prefixo /v1/iam. A Console usa as mesmas rotas.

• Autenticação: token de acesso do seu tenant, obtido pela CLI da NNumbers, no cabeçalho Authorization.
• Tenant: vem sempre do token. Nenhuma rota de tenant recebe o tenant como parâmetro, e um recurso de outro tenant responde 404.
• Autorização: cada rota exige uma permissão iam.*; a API confere em toda requisição.

Rotas

Método e rota	Permissão	Resposta
GET /v1/iam/overview	iam.user.read	estado do IAM no tenant
GET /v1/iam/products	iam.access.read	produtos ativos visíveis ao tenant
GET /v1/iam/products/{product}/roles	iam.access.read	papéis de um produto, com as permissões
GET /v1/iam/users	iam.user.read	usuários, com q, status, cursor e limit; source (local ou external_directory)
POST /v1/iam/users	iam.user.manage	criar usuário (202): {email, first_name?, last_name?, send_invite}; e-mail em uso = 409 user_already_exists
GET /v1/iam/users/{user_id}	iam.user.read	usuário, grupos e o último convite (invitation)
GET /v1/iam/users/{user_id}/security	iam.user.read	segurança lida na hora: MFA, login federado, senha, pendências e last_login
POST /v1/iam/users/{user_id}/invite	iam.user.manage	reenviar o convite (202; só pendente)
POST /v1/iam/users/{user_id}/reset-password	iam.user.manage	resetar a senha por e-mail (202)
POST /v1/iam/users/{user_id}/enable e …/disable	iam.user.manage	habilitar e desabilitar (202)
DELETE /v1/iam/users/{user_id}	iam.user.manage	excluir (202)
GET /v1/iam/users/{user_id}/access	iam.access.read	acesso por produto
GET /v1/iam/users/{user_id}/effective-permissions	iam.access.read	permissões efetivas com a origem
POST /v1/iam/users/{user_id}/grants	iam.access.manage	conceder papel (202)
DELETE /v1/iam/users/{user_id}/grants/{grant_id}	iam.access.manage	revogar (202)
GET /v1/iam/grants	iam.access.read	concessões, com subject, product e state; subject_name (o nome de quem recebeu)
GET /v1/iam/groups	iam.group.read	grupos
GET /v1/iam/groups/{group_id}/members	iam.group.read	membros
GET /v1/iam/service-accounts	iam.service_account.read	service accounts e capability (se a função está pronta no tenant)
POST /v1/iam/service-accounts	iam.service_account.manage	criar (202): {name, description?, roles, delivery_key}; papéis exigem também iam.access.manage
GET /v1/iam/service-accounts/{sa_id}	iam.service_account.read	service account e last_used
PATCH /v1/iam/service-accounts/{sa_id}	iam.service_account.manage	editar nome, descrição e papéis (202)
POST /v1/iam/service-accounts/{sa_id}/rotate	iam.service_account.manage	girar o segredo (202): {delivery_key}
GET /v1/iam/service-accounts/{sa_id}/delivery?operation_id=	iam.service_account.manage	o segredo cifrado da criação ou do giro (secret_jwe), só para quem pediu e até 1 hora depois
POST /v1/iam/service-accounts/{sa_id}/enable e …/disable	iam.service_account.manage	ativar e desativar (202)
DELETE /v1/iam/service-accounts/{sa_id}	iam.service_account.manage	revogar (202)
GET /v1/iam/federation/providers	iam.federation.read	provedores de identidade (com redirect_uri), capability e redirect_base (a URL de retorno de um provedor é <redirect_base>/<identificador>/endpoint)
GET /v1/iam/federation/intake-key	iam.federation.manage	a chave pública para cifrar o segredo do provedor
GET /v1/iam/federation/providers/{alias}	iam.federation.read	provedor, o último teste de conexão e a URL de retorno (redirect_uri)
PUT /v1/iam/federation/providers/{alias}	iam.federation.manage	criar ou alterar (202): {type, display_name, client_id, client_secret_jwe?, discovery_url?, tenant_id?, scopes?, domain_hint?, enabled?}
POST /v1/iam/federation/providers/{alias}/test, …/enable e …/disable	iam.federation.manage	testar a conexão, ativar e desativar (202)
DELETE /v1/iam/federation/providers/{alias}	iam.federation.manage	remover (202)
GET /v1/iam/security	iam.security.read	a política lida na hora e a guarda do login por senha
PUT /v1/iam/security	iam.security.manage	aplicar a política (202): {mfa, password, session, password_login}
GET /v1/iam/actions/{action_id}	iam.action.read	estado de uma operação

O IAM administra só o tenant do token: não há rota que leia ou altere outro tenant.

Paginação

As listas devolvem next_cursor. Para a próxima página, repita a chamada com cursor=<next_cursor>; null quer dizer que acabou. O limit vai de 1 a 200 (padrão 50).

Mutações assíncronas

Toda mutação:

1. exige o cabeçalho Idempotency-Key (até 128 caracteres). Repetir a chamada com a mesma chave devolve a mesma operação, sem efeito duplo;
2. responde 202 com uma Action e o cabeçalho Location;
3. termina quando a Action chega a succeeded, failed ou cancelled. Consulte GET /v1/iam/actions/{action_id} com espera crescente (de 1 a 10 segundos).

Exemplo de corpo para conceder um papel:

{"role": "infinite-data.viewer"}

Exemplo de corpo para criar um usuário com o convite (o resultado da Action traz user_id e invitation):

{"email": "ana@acme.com.br", "first_name": "Ana", "send_invite": true}

O papel é o nome qualificado <produto>.<papel>, como aparece em GET /v1/iam/products/{product}/roles, ou tenant.owner.

Segredos cifrados

Nenhum segredo trafega em claro pela API do IAM. Os dois formatos usam JWE compacto (RFC 7516) com alg: ECDH-ES+A256KW, enc: A256GCM e chaves EC P-256:

• Service account (entrega): gere um par de chaves efêmero e mande só a chave pública em delivery_key (exemplo abaixo; nunca o d). Quando a Action da criação ou do giro termina com delivery: true, busque a entrega com o operation_id do resultado e abra o secret_jwe com a sua chave privada. A entrega vale 1 hora e só para quem fez o pedido;
• Provedor de identidade (intake): leia a chave de GET /v1/iam/federation/intake-key e mande o segredo do aplicativo cifrado para ela em client_secret_jwe, com o kid da chave.

{"kty": "EC", "crv": "P-256", "x": "<x em base64url>", "y": "<y em base64url>", "use": "enc"}

GET /v1/iam/service-accounts/{sa_id}/delivery?operation_id={operation_id}

Erros

Os erros seguem o envelope padrão da Console, com code, reason, message, retryable e correlation_id. Os motivos do IAM estão em Solução de problemas. retryable: true quer dizer que repetir com a mesma Idempotency-Key é seguro.

Depois de uma revogação, requisições com um token anterior recebem 401 reauth_required: obtenha um token novo.