Autenticación

Toda solicitud a la API debe autenticarse. Edugoverna distingue dos credenciales para integradores — la credencial Bearer de la Partner API y la API key de organización — y cada una funciona solo en su propia superficie: enviar una en las rutas de la otra produce un 401, nunca un acceso degradado. En esta guía verás cómo se emite cada credencial, qué verifica el servidor en cada llamada y cómo manejar los secretos de forma segura.

Credencial de Partner API (Bearer)

La credencial de partner autentica a una plataforma externa que opera datos de uno o más colegios. En texto plano tiene la forma keyId.secret — un UUID como identificador y un secreto de 32 caracteres hexadecimales — y se envía completa en el encabezado Authorization:

Solicitud con credencial de partner

curl "https://app.edugoverna.com/api/partner/v1/organizations/{organizationId}/directory/subjects" \
  -H "Authorization: Bearer {keyId}.{secret}"

El servidor no almacena el secreto: guarda el hash SHA-256 de la credencial completa y un prefijo (los primeros 12 caracteres) que la consola usa para identificarla. Por eso el valor en texto plano se muestra una única vez, al emitirla en Integraciones → Partners. Una credencial lleva además una etiqueta, un conjunto de permisos partner.*, una fecha de expiración opcional y una marca de sandbox.

Las cuatro puertas, en orden

Autenticarse no basta: cada solicitud a una ruta de partner atraviesa cuatro verificaciones encadenadas, y la primera que falla determina la respuesta. Esto te permite diagnosticar un rechazo con precisión a partir del código de error:

Nombre
1. Credencial
Tipo
401
Descripción
La credencial existe, está activa (no revocada) y no ha expirado. Si no: PARTNER_CREDENTIAL_INVALID o PARTNER_CREDENTIAL_EXPIRED.
Nombre
2. Conexión
Tipo
403
Descripción
Existe una conexión organization_partner_connection activa entre tu cuenta de partner y la organización de la URL. Si no: PARTNER_CONNECTION_NOT_ACTIVE. Aquí también se verifica que tu propia cuenta de partner esté activa en Edugoverna (PARTNER_WORKSPACE_NOT_ACTIVE si está suspendida o pendiente).
Nombre
3. Contrato (Art. 15 bis)
Tipo
403
Descripción
La conexión tiene un DPA ejecutado y vigente. Si no: PARTNER_DPA_NOT_ACTIVE. Para conexiones de registro externo, el contrato exigido es la declaración jurada del registrador.
Nombre
4. Permiso × alcance
Tipo
403
Descripción
La credencial tiene el permiso partner.* que la ruta exige (PARTNER_PERMISSION_REQUIRED si no), y la conexión otorga el alcance correspondiente, por ejemplo subjects:read (PARTNER_SCOPE_REQUIRED si no). Las condiciones del alcance — como limitar la lectura a titulares activos — moldean la respuesta.

Entre la puerta 3 y la 4 se descuenta además el límite de tasa de tu credencial: una ventana agotada responde 429 PARTNER_RATE_LIMITED antes de evaluar permisos y alcances.

El colegio controla las puertas 2 a 4 desde su consola en cualquier momento: pausar la conexión, dejar vencer el DPA o retirar un alcance corta el acceso de inmediato, sin tocar tu credencial. Cada decisión — permitida o denegada — queda registrada en la auditoría del colegio con tu cuenta de partner como actor.

Los permisos asignables a una credencial de partner 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.

Las dos superficies de credenciales nunca aceptan el token de la otra. Si envías el encabezado x-api-key a una ruta /partner/v1/... — incluso junto a un Bearer válido — la solicitud se rechaza con 401 PARTNER_BEARER_REQUIRED antes de evaluar nada más, y el intento queda auditado.

API key de organización

La API key de organización autentica los scripts e integraciones propias de un colegio. Se envía en el encabezado x-api-key y la key resuelve por sí sola la organización a la que pertenece — las rutas de organización no llevan el tenant en la URL:

Solicitud con API key de organización

curl "https://app.edugoverna.com/api/data-subjects" \
  -H "x-api-key: {api_key}"

Las keys se crean en la consola, en Integraciones → API keys, con un permiso o más del catálogo asignable a keys — 28 permisos que cubren padrón (subjects.read.*, subjects.write, students.*, guardians.*), consentimientos (consents.read, consents.write), derechos (rights_requests.*), gobernanza (processing_activities.*, dpia.read, transparency.read), padrones compartidos (registry_shares.*, shared_subjects.read, shared_campaigns.write), integraciones (integrations.*), auditoría (audit.read) y más. Una key solo puede hacer lo que sus permisos nombran; todo lo demás responde 403.

Una solicitud sin el encabezado responde 401 API_KEY_REQUIRED; una key inexistente, 401 INVALID_API_KEY; una key revocada, 401 KEY_DISABLED. Al igual que la credencial de partner, el valor completo se muestra una sola vez al crearla.

Administra credenciales y API keys

Otros principales

Existen dos formas más de autenticación que verás mencionadas en estas páginas, pero que no están pensadas para integradores:

Sesión de miembro — la cookie de sesión de la consola web. Varias rutas de organización aceptan sesión o API key; algunas operaciones sensibles exigen sesión de miembro y responden MEMBER_SESSION_REQUIRED ante una key.
Tokens de portal público — los enlaces firmados de un solo uso que reciben apoderados y titulares (portales de consentimiento y ARCO). Los emite y consume la propia plataforma.

Recomendaciones de seguridad

Nunca incrustes la credencial en el código ni la subas a un repositorio. Cárgala desde una variable de entorno o un gestor de secretos.
Usa una credencial por sistema. Si dos servicios tuyos llaman a la API, pide credenciales separadas: el prefijo visible permite distinguirlas en la consola y revocar una sin afectar a la otra.
Rota periódicamente. Emite la credencial nueva, despliega, y revoca la anterior. La revocación es inmediata.
Pide el mínimo. Solicita solo los permisos y alcances que tu integración usa hoy; ampliar después es una operación de consola, no un cambio de código.
Ante una sospecha de filtración, revoca primero. La credencial comprometida deja de servir en la solicitud siguiente, y la auditoría del colegio conserva qué hizo mientras estuvo activa.