Gestiona socios por API

Crea, lee, cambia y elimina socios con la Identity API, lee los catálogos de ámbito de los productos, crea aplicaciones de socios y maneja los códigos de error.

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

Antes de empezar

---

Para gestionar socios, un usuario necesita los permisos partners de plugin-identity: get para leer socios y catálogos de ámbito, post para crear un socio, patch para cambiar uno y delete para eliminar uno. Gestionar sus aplicaciones necesita los permisos applications get, post y delete. El rol plugin-identity-editor-role los tiene todos.

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 crea ninguna aplicación.	Crear un socio
GET /v1/partners/{id}	Devuelve un socio.	Consultar un socio
PATCH /v1/partners/{id}	Cambia un socio: su nombre, sus permisos, su ámbito, 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 el producto que nombra el parámetro de consulta product.	Consultar el techo de socios de un producto
GET /v1/scope-catalog	Lista los catálogos de ámbito que publicaron los productos, con partners para cada uno.	Listar catálogos de ámbito
GET /v1/scope-catalog/{product}	Devuelve el catálogo de ámbito de un producto. Un producto sin catálogo devuelve 404 con IDE-1053.	Consultar el catálogo de ámbito de un producto

Para saber qué dimensiones acepta un producto en scope, lee su catálogo de ámbito. Cada dimensión tiene un name y los indicadores required, multi y explicit.

Los campos del socio

---

Campo	Obligatorio al crear	Significado
displayName	Sí	El nombre del socio, de 1 a 100 caracteres. Una letra con tilde, y cualquier otro carácter fuera del ASCII simple, cuenta como dos o más. Un nombre más largo se rechaza. El nombre es único en tu tenant, y la comparación ignora mayúsculas y minúsculas.
permissions	Sí	Una o más entradas, cada una con sus propios product, resources y actions. Cada entrada necesita al menos un recurso y una acción.
scope	Sí, para cada producto cuyo catálogo de ámbito declara dimensiones	Una entrada por restricción: product, field y values. field es el name de una dimensión del catálogo de ámbito del producto.
ipAllowlist	No	La lista de IP permitidas propia del socio. Cada entrada tiene un cidr y una description opcional de hasta 255 caracteres.
validFrom	No	El inicio de la ventana de validez, como un instante RFC 3339. Si falta, no hay fecha de inicio.
validUntil	No	El fin de la ventana de validez, como un instante RFC 3339. Si falta, no hay fecha de fin.
state	No se acepta	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 el slug de producto que trae el catálogo de ámbito del producto, como plugin-br-pix-jd.
• Escribe actions en minúsculas, como las devuelve Consultar el techo de socios de un producto: verbos HTTP como get, post, patch y delete en Midaz, Pix JD y Reporter, y acciones nombradas como read y activate en Flowker.
• resources × actions es un producto cartesiano completo. Para dar acciones distintas sobre recursos distintos, envía más de una entrada para el mismo producto.
• Access Manager rechaza el comodín * en resources, actions y values. Lista los elementos.
• Un producto en scope también debe estar en permissions.
• Un producto cuyo catálogo de ámbito declara dimensiones necesita al menos una entrada de ámbito en cada socio con permisos en ese producto. La excepción es una entrada de permisos que tiene solo permisos que el producto reserva para socios: no necesita ámbito, y aplica a todo el tenant. Sin una entrada de ámbito, Access Manager rechaza crear o cambiar el socio, con IDE-1060. Un socio guardado sin ella antes de esta regla se rechaza con 403 en cada solicitud a ese producto, hasta que agregues una entrada de ámbito.
• Una dimensión que el catálogo marca como required necesita una entrada de ámbito en cada socio con permisos en ese producto, o Access Manager rechaza con IDE-0001. Una dimensión sin multi acepta solo un valor, o Access Manager rechaza con IDE-0002.
• Para una dimensión que el catálogo marca como explicit, un permiso sobre la colección de esa dimensión necesita una entrada de ámbito que liste sus IDs. Sin ella, Access Manager rechaza con IDE-1052. El socio alcanza solo los IDs que listas.
• Access Manager no verifica que los values existan en el producto. Usa los identificadores que devuelve la propia API del producto.
• state es active o suspended, nunca expired. Después de validUntil, una lectura sigue devolviendo el estado guardado.
• Después de la fecha validUntil del socio, Access Manager rechaza sus solicitudes, también con un token que ya tiene, y rechaza tokens nuevos.

El campo de lista de IP permitidas

---

ipAllowlist tiene tres significados en PATCH:

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 la lista de tu tenant.
Una lista de entradas	Estas entradas reemplazan la lista propia del socio.
[]	Rechazado con IDE-1048.

Cada entrada de la lista propia del socio debe ser un rango IPv4 de /24 o más estrecho, o un rango IPv6 de /48 o más estrecho. Una entrada más amplia se rechaza con IDE-1052. Una entrada que el socio ya tiene no se verifica de nuevo.

En POST, omite el campo o envía null para usar la lista de tu tenant.

Cuando un socio tiene su propia lista de IP, esa lista reemplaza la lista de IP del tenant para las solicitudes del socio.

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, tu bearer token e identificadores de tu propio despliegue.

Create a partner

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": "plugin-br-pix-jd", "resources": ["entries"], "actions": ["get", "post"] }
    ],
    "scope": [
      { "product": "plugin-br-pix-jd", "field": "participantId", "values": ["12345678"] }
    ],
    "ipAllowlist": [
      { "cidr": "203.0.113.10", "description": "Partner A gateway" }
    ]
  }'

Crea las aplicaciones del socio

---

Un socio llama a un producto con una aplicación que le pertenece. Después de crear el socio:

1. Crea una aplicación con Crear una aplicación. Envía el id del socio en partnerId y el slug del producto en target, como plugin-br-pix-jd.
2. La Identity API devuelve el client secret solo en la respuesta que crea la aplicación. Guárdalo en ese momento. Si pierdes el secret, elimina la aplicación y crea una nueva.
3. Envía el client ID y el secret al socio por un canal seguro.
4. Repite los pasos 1 a 3 para cada producto al que llama el socio. Crea una aplicación por producto.

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.

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".
• Suspender un socio en Access Manager detiene su acceso, incluidos los tokens que ya tiene. Reactivar el socio dentro de su ventana de validez restaura el acceso con las mismas credenciales.
• Cuándo se aplica un cambio indica cuándo el socio ve un cambio de permisos o de ámbito.
• 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.
• Eliminar una aplicación hace que sus tokens dejen de funcionar.

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	Una dimensión que acepta un valor recibió varios.
IDE-0036	400	Invalid IP Allowlist Entry	Una entrada de ipAllowlist no es una dirección ni 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, o el producto no tiene catálogo de ámbito.
IDE-1043	400	Permission Above Product Ceiling	Un permiso está por encima del techo 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, actions o values.
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-1052	400	Partner Rejected	El proveedor de identidad rechazó el socio por otro motivo, por ejemplo un permiso sobre la colección de una dimensión explicit sin sus IDs, o un permiso que ninguna solicitud del socio puede usar dentro de su ámbito. El mensaje repite ese motivo.
IDE-1053	404	Scope Catalog Not Found	El producto no publicó un catálogo de ámbito.
IDE-1054	400	Product Not Ready For Partners	Un permiso nombra un producto que no publicó su catálogo de ámbito.
IDE-1055	400	Product Not Opted In To Partners	Un permiso nombra un producto cuyo catálogo de ámbito no acepta socios.
IDE-1056	400	Partner Write Exceeds Its Scope	Un permiso de escritura actúa en un nivel más amplio que el ámbito del socio.
IDE-1057	400	Partner Read Rejected	El proveedor de identidad rechazó la lectura del techo, por ejemplo para un producto desconocido.
IDE-1060	400	Partner Product Without Scope	Un permiso que el producto no reserva para socios nombra un producto cuyo catálogo de ámbito declara dimensiones, y scope no tiene una entrada para ese producto. En PATCH, quitar la última entrada de ámbito de un producto que conserva sus permisos también se rechaza.

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