Gerenciar parceiros pela API

Esta funcionalidade está disponível apenas em Staging para testes e ainda não está disponível em Produção.

A Identity API gerencia parceiros e as credenciais deles. Use-a quando você gerencia parceiros pelas suas próprias ferramentas em vez do Console.

As operações

Operação	O que faz	Referência
`GET /v1/partners`	Lista os seus parceiros, uma página por vez, com `applicationsCount` para cada um.	Listar parceiros
`POST /v1/partners`	Cria um parceiro. Retorna `201` com o novo parceiro e o `id` dele. Nenhuma credencial é criada.	Criar um parceiro
`GET /v1/partners/{id}`	Retorna um parceiro completo.	Consultar um parceiro
`PATCH /v1/partners/{id}`	Altera um parceiro: o acesso, a janela de validade, a lista de IPs permitidos ou o estado dele.	Atualizar um parceiro
`DELETE /v1/partners/{id}`	Exclui um parceiro sem aplicações. Retorna `204`.	Excluir um parceiro
`GET /v1/partners/ceiling`	Retorna o máximo que você pode dar a um parceiro em um produto.	—

Toda operação precisa de um bearer token com a permissão partners. O Access Manager identifica o seu tenant pelo token. Não existe campo de tenant no caminho nem no corpo, e você nunca vê os parceiros de outro tenant. Para saber quais restrições um produto aceita, leia o catálogo de escopo dele com GET /v1/scope-catalog/{product}.

Os campos do parceiro

Campo	Obrigatório na criação	Significado
`displayName`	Sim	O nome do parceiro, de 1 a 128 caracteres, único no seu tenant.
`permissions`	Sim	Uma ou mais entradas por produto, cada uma com seus próprios `product`, `resources` e `actions`. Cada entrada precisa de pelo menos um recurso e uma ação.
`scope`	Não	Uma entrada por restrição: `product`, `field` e `values`. `field` é uma dimensão do catálogo de escopo do produto, como `organizationId` ou `ledgerId`.
`ipAllowlist`	Não	A lista de IPs permitidos própria do parceiro. Cada entrada tem um `cidr` e uma `description` opcional.
`validFrom`	Não	O início da janela de validade, como um instante RFC 3339. Ausente significa “válido agora”.
`validUntil`	Não	O fim da janela de validade, como um instante RFC 3339. Ausente significa “sem data de fim”.
`state`	Não	`active` ou `suspended`. Todo parceiro novo é `active`. Você o altera com `PATCH`.

A resposta também traz id, applicationsCount, createdAt e updatedAt. Regras que valem para os campos:

product é um slug de produto de Listar aplicações disponíveis, como midaz.
actions são verbos HTTP em minúsculas: get, post, put, patch, delete. head vem junto com get.
O curinga * não é aceito em resources nem em actions. Liste os valores.
Um produto em scope também precisa estar em permissions.
O Midaz exige um organizationId para cada parceiro com permissões no Midaz. Uma dimensão que o catálogo não marca como de vários valores aceita só um valor.
O Access Manager não confere se os values existem no produto. Use os IDs que a própria API do produto retorna.
state nunca mostra expired. Depois de validUntil, o parceiro continua active, com um validUntil no passado.

O campo de lista de IPs permitidos

ipAllowlist tem três significados no PATCH, e eles não são iguais:

Você envia	O que acontece
O campo omitido	A lista guardada continua como está.
`null`	A lista própria do parceiro é excluída. O parceiro volta a usar a lista do seu tenant.
Uma lista de entradas	A lista própria do parceiro é substituída por estas entradas.
`[]`	Recusado com `IDE-1048`. Para bloquear um parceiro por completo, suspenda-o.

No POST, omita o campo ou envie null para usar a lista do seu tenant. A lista própria de um parceiro substitui a lista do seu tenant. Ela não se soma a ela. validFrom e validUntil funcionam de forma parecida no PATCH: omita um limite para mantê-lo, envie um instante para defini-lo ou envie null para removê-lo.

Exemplos

Troque os placeholders pela URL base da sua Identity API, por um bearer token que tenha a permissão partners e por IDs da sua própria organização do Midaz.

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X POST "${IDENTITY_BASE_URL}/v1/partners" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Partner A",
    "permissions": [
      { "product": "midaz", "resources": ["accounts"], "actions": ["get", "post", "patch"] },
      { "product": "midaz", "resources": ["transactions"], "actions": ["get", "post"] }
    ],
    "scope": [
      { "product": "midaz", "field": "organizationId", "values": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"] },
      { "product": "midaz", "field": "ledgerId", "values": ["9c858901-8a57-4791-81fe-4a34d4dd8ab5"] }
    ],
    "ipAllowlist": [
      { "cidr": "203.0.113.10", "description": "Partner A gateway" }
    ]
  }'

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X POST "${IDENTITY_BASE_URL}/v1/applications" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "midaz",
    "description": "Partner A access to Midaz",
    "partnerId": "'"${PARTNER_ID}"'"
  }'

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "state": "suspended" }'

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "ipAllowlist": null }'

Emitir as credenciais do parceiro

Um parceiro sem aplicação não consegue chamar nada. Depois de criar o parceiro:

Crie uma aplicação com Criar uma aplicação e envie o id do parceiro em partnerId. Defina name como o slug do produto, como midaz. Crie uma aplicação por produto.
Copie clientId e clientSecret da resposta. A resposta é a única vez em que o segredo aparece.
Envie os dois valores ao parceiro por um canal seguro.

Para listar as aplicações de um parceiro, envie o id dele no parâmetro de consulta partnerId de Listar aplicações. Se partnerId não nomear um parceiro do seu tenant, as duas operações retornam 404 com IDE-1046, e nada é criado.

Alterar, suspender ou excluir um parceiro

No PATCH, envie só os campos que você altera. Uma lista permissions ou scope substitui a lista guardada inteira. Leia o parceiro antes e depois envie a nova lista completa.
Para suspender um parceiro, envie "state": "suspended". Para reativá-lo, envie "state": "active".
Uma alteração vale a partir da próxima requisição do parceiro. Uma suspensão também recusa os tokens que o parceiro já tem.
Você não pode excluir um parceiro que ainda tem aplicações. A resposta é 409 com IDE-1049, e a lista errors dela nomeia cada aplicação que bloqueia, com o client ID. Exclua essas aplicações antes.

Códigos de erro

Erros nas operações de parceiro:

Código	Status	Título	Quando
`IDE-0001`	400	Missing Fields in Request	Falta um campo obrigatório, ou o escopo não tem entrada para uma dimensão que o produto exige.
`IDE-0002`	400	Invalid Field Type in Request	Vários valores em uma dimensão de valor único, ou um `state` diferente de `active` ou `suspended`.
`IDE-0036`	400	Invalid IP Allowlist Entry	Uma entrada de `ipAllowlist` não é um endereço ou uma faixa CIDR válida.
`IDE-1040`	409	Partner Display Name Already Exists	Outro parceiro do seu tenant tem o mesmo `displayName`.
`IDE-1042`	400	Unknown Scope Field	Um `field` de escopo não está no catálogo de escopo do produto.
`IDE-1043`	400	Permission Above Product Ceiling	Uma permissão está acima do que o papel de editor do produto tem no seu tenant.
`IDE-1044`	400	Scope Without Permissions	Um produto está em `scope`, mas não em `permissions`.
`IDE-1045`	400	Invalid Validity Window	`validUntil` não é posterior a `validFrom`.
`IDE-1046`	404	Partner Not Found	Não existe parceiro com este `id` no seu tenant.
`IDE-1047`	400	Wildcard Not Allowed	`*` está em `resources` ou em `actions`.
`IDE-1048`	400	Empty IP Allowlist	`ipAllowlist` é um array vazio.
`IDE-1049`	409	Partner Has Applications	O parceiro ainda tem aplicações, então não pode ser excluído.
`IDE-1050`	400	Duplicate IP Allowlist Entry	A mesma rede aparece duas vezes em `ipAllowlist`.
`IDE-1054`	400	Product Not Ready For Partners	O produto ainda não publicou o catálogo de escopo dele.
`IDE-1055`	400	Product Not Opted In To Partners	O produto tem catálogo de escopo, mas não aceita parceiros.
`IDE-1056`	400	Partner Write Exceeds Its Scope	Uma escrita atua em um nível mais amplo que o escopo do parceiro, como criar ledgers para um parceiro restrito a um ledger.

Erros que o próprio sistema do parceiro recebe:

Código	Status	Quando
`AUT-0021`	403	A requisição vem de um endereço fora da lista de IPs permitidos do parceiro.
`AUT-1009`	401	O parceiro está suspenso. Retornado nas requisições aos produtos e nos pedidos de token novo.
`AUT-1010`	401	O parceiro está fora da janela de validade dele. Retornado nas requisições aos produtos e nos pedidos de token novo.
Nenhum	403	As permissões ou o escopo não permitem a requisição. O produto não diz qual dos dois.

Para qualquer outro código, consulte a lista de erros do Access Manager.

Primeiros passos

Funcionalidades

Deploy e operações

Arquitetura

Provedor de identidade (Caradhras)

Gerenciar parceiros pela API

As operações

Os campos do parceiro

O campo de lista de IPs permitidos

Exemplos

Emitir as credenciais do parceiro

Alterar, suspender ou excluir um parceiro

Códigos de erro

​As operações

​Os campos do parceiro

​O campo de lista de IPs permitidos

​Exemplos

​Emitir as credenciais do parceiro

​Alterar, suspender ou excluir um parceiro

​Códigos de erro

As operações

Os campos do parceiro

O campo de lista de IPs permitidos

Exemplos

Emitir as credenciais do parceiro

Alterar, suspender ou excluir um parceiro

Códigos de erro