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 provedor de identidade 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
GET /v1/iam/users/{user_id}	iam.user.read	usuário e grupos
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
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	503 capability_not_ready (capacidade ainda não disponível)
GET /v1/iam/federation/providers	iam.federation.read	503 capability_not_ready (capacidade ainda não disponível)
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"}

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

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.