Credenciales de partner

Una credencial de partner es la llave con que un proveedor tecnológico (plataforma de gestión escolar, software de convivencia, etc.) llama a la API de partner en nombre de su relación con tu establecimiento. En esta página verás cómo emitirlas, ajustar sus límites de tasa y revocarlas mediante la API de gestión.

Todo lo descrito aquí también se puede hacer desde la Consola, en Integraciones. La API de gestión existe para automatizar el mismo flujo. Las rutas de esta página aceptan sesión de la Consola o una API key de organización en la cabecera x-api-key, y exigen el permiso integrations.write.

Una credencial pertenece a una cuenta de partner, y tu organización solo puede operar sobre credenciales de partners con los que tiene una conexión. Ten presente que la credencial por sí sola no da acceso: cada llamada del partner pasa además por las puertas de la conexión (estado, scopes y DPA vigente).

El modelo de credencial

Las respuestas de esta API devuelven la credencial en su forma segura: nunca incluyen el hash de la llave, y la llave en texto plano solo aparece una vez, en la respuesta de emisión.

Propiedades

Nombre
id
Tipo
string
Descripción
Identificador único de la credencial.
Nombre
partnerAccountId
Tipo
string
Descripción
La cuenta de partner a la que pertenece.
Nombre
label
Tipo
string
Descripción
Etiqueta descriptiva, por ejemplo «Producción — sincronización de padrón».
Nombre
keyId
Tipo
string
Descripción
La mitad pública de la llave (el segmento antes del punto).
Nombre
prefix
Tipo
string
Descripción
Los primeros 12 caracteres de la llave, para reconocerla en listados sin exponerla.
Nombre
status
Tipo
string
Descripción
active o revoked.
Nombre
permissions
Tipo
array de strings
Descripción
Los permisos partner.* concedidos a la credencial, ordenados alfabéticamente.
Nombre
rateLimitWindowSeconds
Tipo
integer
Descripción
Largo de la ventana de límite de tasa, en segundos. Por defecto 60.
Nombre
rateLimitMaxRequests
Tipo
integer
Descripción
Máximo de solicitudes por ventana. Por defecto 600.
Nombre
isSandbox
Tipo
boolean
Descripción
Si la credencial opera en modo sandbox (datos de prueba, sin envíos reales). Por defecto false.
Nombre
expiresAt
Tipo
timestamp
Descripción
Vencimiento opcional; una credencial vencida es rechazada con PARTNER_CREDENTIAL_EXPIRED.
Nombre
lastUsedAt
Tipo
timestamp
Descripción
Última vez que la credencial autenticó una llamada.

Permisos asignables

El arreglo permissions solo acepta permisos del plano de partner. Los disponibles son:

partner.subjects.read, partner.subjects.write, partner.guardianships.write, partner.enrollments.write, partner.consents.read, partner.consents.write, partner.processing_activities.read, partner.processing_activities.write, partner.rights_requests.read, partner.rights_requests.write, partner.arco_portals.read, partner.arco_portals.write, partner.shared_subjects.read y partner.shared_campaigns.write.

Cualquier otro nombre es rechazado en la validación.

POST/api/integrations/partner-credentials

Emitir una credencial

Emite una credencial nueva para una cuenta de partner conectada a tu organización. La respuesta 201 incluye plainTextKey — la llave completa en texto plano — una única vez: guárdala de inmediato en un lugar seguro, porque no hay forma de recuperarla después.

Atributos obligatorios

Nombre
partnerAccountId
Tipo
string
Descripción
UUID de la cuenta de partner. Debe existir una conexión entre tu organización y ese partner.
Nombre
label
Tipo
string
Descripción
Etiqueta descriptiva (2–160 caracteres).

Atributos opcionales

Nombre
permissions
Tipo
array de strings
Descripción
Permisos partner.* a conceder. Ver Permisos asignables.
Nombre
expiresAt
Tipo
string (fecha)
Descripción
Vencimiento de la credencial.
Nombre
isSandbox
Tipo
boolean
Descripción
Emite la credencial en modo sandbox.

Solicitud

POST

/api/integrations/partner-credentials

curl https://app.edugoverna.com/api/integrations/partner-credentials \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerAccountId": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "label": "Producción — sincronización de padrón",
    "permissions": ["partner.subjects.read", "partner.consents.write"],
    "isSandbox": false
  }'

Respuesta (201)

{
  "credential": {
    "id": "0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e",
    "partnerAccountId": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "label": "Producción — sincronización de padrón",
    "keyId": "9e2a41d7-6c3b-4f0e-8a17-b5d4c2e8f901",
    "prefix": "9e2a41d7-6c3",
    "status": "active",
    "permissions": ["partner.subjects.read", "partner.consents.write"],
    "rateLimitWindowSeconds": 60,
    "rateLimitMaxRequests": 600,
    "isSandbox": false,
    "expiresAt": null,
    "lastUsedAt": null
  },
  "plainTextKey": "9e2a41d7-6c3b-4f0e-8a17-b5d4c2e8f901.f47ac10b58cc4372a5670e02b2c3d479",
  "maskedKey": "*****************************************************************d479"
}

PATCH/api/integrations/partner-credentials/:id

Ajustar límites y sandbox

Modifica el límite de tasa o el modo sandbox de una credencial existente. Debes enviar al menos uno de los tres campos.

Atributos opcionales

Nombre
rateLimitWindowSeconds
Tipo
integer
Descripción
Largo de la ventana en segundos, entre 1 y 86.400. Un valor fuera de rango responde 422 con el código PARTNER_RATE_LIMIT_WINDOW_INVALID.
Nombre
rateLimitMaxRequests
Tipo
integer
Descripción
Máximo de solicitudes por ventana, entre 1 y 1.000.000. Fuera de rango responde 422 con PARTNER_RATE_LIMIT_MAX_INVALID.
Nombre
isSandbox
Tipo
boolean
Descripción
Activa o desactiva el modo sandbox de la credencial. El carácter sandbox de una solicitud de consentimiento se fija al crearla, por lo que cambiar este valor no afecta retroactivamente lo ya creado.

Cuando el partner agota su cuota, la API de partner responde 429 hasta que la ventana se renueva. Ver Límites de tasa.

Solicitud

PATCH

/api/integrations/partner-credentials/:id

curl -X PATCH https://app.edugoverna.com/api/integrations/partner-credentials/0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "rateLimitWindowSeconds": 60,
    "rateLimitMaxRequests": 1200
  }'

Respuesta

{
  "id": "0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e",
  "status": "active",
  "rateLimitWindowSeconds": 60,
  "rateLimitMaxRequests": 1200,
  "isSandbox": false
  // ... resto de la credencial
}

POST/api/integrations/partner-credentials/:id/revoke

Revocar una credencial

Revoca la credencial de forma permanente. Las llamadas siguientes del partner con esa llave son rechazadas con 401 y el código PARTNER_CREDENTIAL_INVALID. La revocación no tiene marcha atrás: para restituir el acceso, emite una credencial nueva.

Revocar una credencial no toca la conexión ni sus scopes; si lo que quieres es cortar la relación completa con el partner, revoca la conexión.

Solicitud

POST

/api/integrations/partner-credentials/:id/revoke

curl -X POST https://app.edugoverna.com/api/integrations/partner-credentials/0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e/revoke \
  -H "x-api-key: {api_key}"

Respuesta

{
  "id": "0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e",
  "status": "revoked"
  // ... resto de la credencial
}

Dónde ver las credenciales existentes

No hay un listado propio en esta API: las credenciales de un partner aparecen (en su forma segura, con prefix pero sin la llave) en el detalle de la conexión, GET /api/integrations/partners/:organizationPartnerConnectionId. Ver Conexiones y partners.