Gestiona socios por API

Esta funcionalidad está disponible solo en Staging para pruebas y todavía no está disponible en Producción.

La Identity API gestiona socios y sus credenciales. Úsala cuando gestionas socios desde tus propias herramientas en lugar de Console.

Las operaciones

Operación	Qué hace	Referencia
`GET /v1/partners`	Lista tus socios, una página a la vez, con `applicationsCount` para cada uno.	Listar socios
`POST /v1/partners`	Crea un socio. Devuelve `201` con el nuevo socio y su `id`. No se crea ninguna credencial.	Crear un socio
`GET /v1/partners/{id}`	Devuelve un socio completo.	Consultar un socio
`PATCH /v1/partners/{id}`	Cambia un socio: su acceso, su ventana de validez, su lista de IP permitidas o su estado.	Actualizar un socio
`DELETE /v1/partners/{id}`	Elimina un socio sin aplicaciones. Devuelve `204`.	Eliminar un socio
`GET /v1/partners/ceiling`	Devuelve lo máximo que puedes dar a un socio en un producto.	—

Cada operación necesita un bearer token con el permiso partners. Access Manager identifica tu tenant a partir del token. No hay un campo de tenant en la ruta ni en el cuerpo, y nunca ves los socios de otro tenant. Para saber qué restricciones acepta un producto, lee su catálogo de ámbito con GET /v1/scope-catalog/{product}.

Los campos del socio

Campo	Obligatorio al crear	Significado
`displayName`	Sí	El nombre del socio, de 1 a 128 caracteres, único en tu tenant.
`permissions`	Sí	Una o más entradas por producto, cada una con sus propios `product`, `resources` y `actions`. Cada entrada necesita al menos un recurso y una acción.
`scope`	No	Una entrada por restricción: `product`, `field` y `values`. `field` es una dimensión del catálogo de ámbito del producto, como `organizationId` o `ledgerId`.
`ipAllowlist`	No	La lista de IP permitidas propia del socio. Cada entrada tiene un `cidr` y una `description` opcional.
`validFrom`	No	El inicio de la ventana de validez, como un instante RFC 3339. Si falta, significa “válido ahora”.
`validUntil`	No	El fin de la ventana de validez, como un instante RFC 3339. Si falta, significa “sin fecha de fin”.
`state`	No	`active` o `suspended`. Todo socio nuevo es `active`. Lo cambias con `PATCH`.

La respuesta también trae id, applicationsCount, createdAt y updatedAt. Reglas que se aplican a los campos:

product es un slug de producto de Listar aplicaciones disponibles, como midaz.
actions son verbos HTTP en minúsculas: get, post, put, patch, delete. head viene con get.
El comodín * no se acepta en resources ni en actions. Lista los valores.
Un producto en scope también debe estar en permissions.
Midaz exige un organizationId para cada socio con permisos en Midaz. Una dimensión que el catálogo no marca como de varios valores acepta un solo valor.
Access Manager no verifica que los values existan en el producto. Usa los IDs que devuelve la propia API del producto.
state nunca muestra expired. Después de validUntil, el socio sigue en active, con un validUntil en el pasado.

El campo de lista de IP permitidas

ipAllowlist tiene tres significados en PATCH, y no son iguales:

Envías	Qué pasa
El campo omitido	La lista guardada queda como está.
`null`	La lista propia del socio se elimina. El socio vuelve a usar la lista de tu tenant.
Una lista de entradas	La lista propia del socio se reemplaza por estas entradas.
`[]`	Rechazado con `IDE-1048`. Para bloquear un socio por completo, suspéndelo.

En POST, omite el campo o envía null para usar la lista de tu tenant. La lista propia de un socio reemplaza la lista de tu tenant. No se suma a ella. validFrom y validUntil funcionan de forma parecida en PATCH: omite un límite para conservarlo, envía un instante para definirlo o envía null para quitarlo.

Ejemplos

Reemplaza los marcadores por la URL base de tu Identity API, un bearer token con el permiso partners e IDs de tu propia organización de 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 }'

Emite las credenciales del socio

Un socio sin aplicación no puede llamar a nada. Después de crear el socio:

Crea una aplicación con Crear una aplicación y envía el id del socio en partnerId. Define name con el slug del producto, como midaz. Crea una aplicación por producto.
Copia clientId y clientSecret de la respuesta. La respuesta es la única vez que se muestra el secreto.
Envía los dos valores al socio por un canal seguro.

Para listar las aplicaciones de un socio, envía su id en el parámetro de consulta partnerId de Listar aplicaciones. Si partnerId no nombra un socio de tu tenant, las dos operaciones devuelven 404 con IDE-1046, y no se crea nada.

Cambia, suspende o elimina un socio

En PATCH, envía solo los campos que cambias. Una lista permissions o scope reemplaza la lista guardada completa. Lee primero el socio y después envía la nueva lista completa.
Para suspender un socio, envía "state": "suspended". Para reactivarlo, envía "state": "active".
Un cambio se aplica desde la siguiente solicitud del socio. Una suspensión también rechaza los tokens que el socio ya tiene.
No puedes eliminar un socio que todavía tiene aplicaciones. La respuesta es 409 con IDE-1049, y su lista errors nombra cada aplicación que bloquea, con su client ID. Elimina primero esas aplicaciones.

Códigos de error

Errores en las operaciones de socios:

Código	Estado	Título	Cuándo
`IDE-0001`	400	Missing Fields in Request	Falta un campo obligatorio, o el ámbito no tiene una entrada para una dimensión que el producto exige.
`IDE-0002`	400	Invalid Field Type in Request	Varios valores en una dimensión de un solo valor, o un `state` distinto de `active` o `suspended`.
`IDE-0036`	400	Invalid IP Allowlist Entry	Una entrada de `ipAllowlist` no es una dirección o un rango CIDR válido.
`IDE-1040`	409	Partner Display Name Already Exists	Otro socio de tu tenant tiene el mismo `displayName`.
`IDE-1042`	400	Unknown Scope Field	Un `field` de ámbito no está en el catálogo de ámbito del producto.
`IDE-1043`	400	Permission Above Product Ceiling	Un permiso está por encima de lo que tiene el rol de editor del producto en tu tenant.
`IDE-1044`	400	Scope Without Permissions	Un producto está en `scope` pero no en `permissions`.
`IDE-1045`	400	Invalid Validity Window	`validUntil` no es posterior a `validFrom`.
`IDE-1046`	404	Partner Not Found	No existe un socio con este `id` en tu tenant.
`IDE-1047`	400	Wildcard Not Allowed	`*` está en `resources` o en `actions`.
`IDE-1048`	400	Empty IP Allowlist	`ipAllowlist` es un arreglo vacío.
`IDE-1049`	409	Partner Has Applications	El socio todavía tiene aplicaciones, así que no se puede eliminar.
`IDE-1050`	400	Duplicate IP Allowlist Entry	La misma red aparece dos veces en `ipAllowlist`.
`IDE-1054`	400	Product Not Ready For Partners	El producto todavía no publicó su catálogo de ámbito.
`IDE-1055`	400	Product Not Opted In To Partners	El producto tiene un catálogo de ámbito pero no acepta socios.
`IDE-1056`	400	Partner Write Exceeds Its Scope	Una escritura actúa en un nivel más amplio que el ámbito del socio, como crear ledgers para un socio restringido a un ledger.

Errores que recibe el propio sistema del socio:

Código	Estado	Cuándo
`AUT-0021`	403	La solicitud viene de una dirección fuera de la lista de IP permitidas del socio.
`AUT-1009`	401	El socio está suspendido. Se devuelve en las solicitudes a los productos y en los pedidos de token nuevo.
`AUT-1010`	401	El socio está fuera de su ventana de validez. Se devuelve en las solicitudes a los productos y en los pedidos de token nuevo.
Ninguno	403	Los permisos o el ámbito no permiten la solicitud. El producto no dice cuál de los dos.

Para cualquier otro código, consulta la lista de errores de Access Manager.

Primeros pasos

Funcionalidades

Despliegue y operaciones

Arquitectura

Proveedor de identidad (Caradhras)

Gestiona socios por API

Las operaciones

Los campos del socio

El campo de lista de IP permitidas

Ejemplos

Emite las credenciales del socio

Cambia, suspende o elimina un socio

Códigos de error

​Las operaciones

​Los campos del socio

​El campo de lista de IP permitidas

​Ejemplos

​Emite las credenciales del socio

​Cambia, suspende o elimina un socio

​Códigos de error

Las operaciones

Los campos del socio

El campo de lista de IP permitidas

Ejemplos

Emite las credenciales del socio

Cambia, suspende o elimina un socio

Códigos de error