---
title: "Credenciales de partner"
description: "Emite, ajusta y revoca credenciales de la API de partner: permisos asignables, límites de tasa, modo sandbox y revocación."
url: "https://docs.edugoverna.com/gestion/credenciales"
---
# 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. {{ className: 'lead' }}

<Note>
  Estas rutas las llama **el colegio**, con su sesión de consola o su API key de
  organización en la cabecera `x-api-key`, y exigen el permiso
  `integrations.write`; tu credencial de partner no sirve aquí. Todo lo descrito
  también se puede hacer desde la Consola, en **Integraciones** — la API de
  gestión existe para automatizar el mismo flujo. Si estás del lado del partner,
  el recorrido escrito para ti es
  [Cómo se habilita tu acceso](/gestion/acceso).
</Note>

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](/gestion/conexiones). 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

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

## 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.

---

## Emitir una credencial {{ tag: 'POST', label: '/api/integrations/partner-credentials' }}

<Row>
  <Col>

    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

    <Properties>
      <Property name="partnerAccountId" type="string">
        UUID de la cuenta de partner. Debe existir una conexión entre tu
        organización y ese partner.
      </Property>
      <Property name="label" type="string">
        Etiqueta descriptiva (2–160 caracteres).
      </Property>
    </Properties>

    ### Atributos opcionales

    <Properties>
      <Property name="permissions" type="array de strings">
        Permisos `partner.*` a conceder. Ver
        [Permisos asignables](#permisos-asignables).
      </Property>
      <Property name="expiresAt" type="string (fecha)">
        Vencimiento de la credencial.
      </Property>
      <Property name="isSandbox" type="boolean">
        Emite la credencial en modo sandbox.
      </Property>
    </Properties>

  </Col>
  <Col sticky>

    <CodeGroup title="Solicitud" tag="POST" label="/api/integrations/partner-credentials">

    ```bash {{ title: 'cURL' }}
    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
      }'
    ```

    ```js
    const response = await fetch(
      'https://app.edugoverna.com/api/integrations/partner-credentials',
      {
        method: 'POST',
        headers: {
          'x-api-key': apiKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          partnerAccountId: '16fd2706-8baf-433b-82eb-8c7fada847da',
          label: 'Producción — sincronización de padrón',
          permissions: ['partner.subjects.read', 'partner.consents.write'],
          isSandbox: false,
        }),
      },
    )
    const { credential, plainTextKey } = await response.json()
    ```

    </CodeGroup>

    ```json {{ title: '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"
    }
    ```

  </Col>
</Row>

---

## Ajustar límites y sandbox {{ tag: 'PATCH', label: '/api/integrations/partner-credentials/:id' }}

<Row>
  <Col>

    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

    <Properties>
      <Property name="rateLimitWindowSeconds" type="integer">
        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`.
      </Property>
      <Property name="rateLimitMaxRequests" type="integer">
        Máximo de solicitudes por ventana, entre 1 y 1.000.000. Fuera de rango
        responde `422` con `PARTNER_RATE_LIMIT_MAX_INVALID`.
      </Property>
      <Property name="isSandbox" type="boolean">
        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.
      </Property>
    </Properties>

    Cuando el partner agota su cuota, la API de partner responde `429` hasta
    que la ventana se renueva. Ver [Límites de tasa](/limites).

  </Col>
  <Col sticky>

    <CodeGroup title="Solicitud" tag="PATCH" label="/api/integrations/partner-credentials/:id">

    ```bash {{ title: 'cURL' }}
    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
      }'
    ```

    ```js
    await fetch(
      'https://app.edugoverna.com/api/integrations/partner-credentials/0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e',
      {
        method: 'PATCH',
        headers: {
          'x-api-key': apiKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          rateLimitWindowSeconds: 60,
          rateLimitMaxRequests: 1200,
        }),
      },
    )
    ```

    </CodeGroup>

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

  </Col>
</Row>

---

## Revocar una credencial {{ tag: 'POST', label: '/api/integrations/partner-credentials/:id/revoke' }}

<Row>
  <Col>

    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](/gestion/conexiones#revocar-una-conexion).

  </Col>
  <Col sticky>

    <CodeGroup title="Solicitud" tag="POST" label="/api/integrations/partner-credentials/:id/revoke">

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

    ```js
    await fetch(
      'https://app.edugoverna.com/api/integrations/partner-credentials/0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e/revoke',
      { method: 'POST', headers: { 'x-api-key': apiKey } },
    )
    ```

    </CodeGroup>

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

  </Col>
</Row>

---

## 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](/gestion/conexiones).