Claves de API

Una clave de API es la credencial que un sistema externo usa para entrar a tu plataforma por la API. Por ejemplo: tu ERP lee alumnos y crea matrículas. La clave solo hace lo que sus permisos permiten. En Configuraciones → Claves de API creas las claves, eliges lo que cada una puede hacer, sigues el uso y revocas. Para quien va a programar la integración, la documentación técnica está en https://cademi.dev/api (botón Documentación).

La idea en un minuto

Cada clave tiene estas partes:

• un nombre y una finalidad, para que reconozcas la clave;
• una o más políticas, que dicen lo que la clave puede hacer y dónde;
• una vigencia, la fecha en que la clave deja de funcionar;
• un secreto, el código que la integración usa para identificarse.

La regla más importante: el secreto aparece una sola vez, cuando se crea la clave. Después, nadie puede ver el secreto de nuevo. Si se pierde, genera otro con Rotar secreto.

La pantalla tiene dos pestañas:

• Claves: las credenciales de la API actual.
• API antigua: las claves de la API anterior.

La lista de claves

La lista muestra, para cada clave:

• Nombre, con el final del secreto, para que sepas cuál es cuál;
• Permisos;
• Último uso;
• Creada;
• Estado: Activa, Suspendida, Expirada o Revocada.

El filtro Estado recorta la lista. Una clave que expira en los próximos siete días muestra el aviso vence con el plazo.

La fila Soporte Cademí es la clave que Cademí usa para atender tus tickets. El artículo El acceso del soporte de Cademí explica lo que hace. También muestra cómo autorizar o retirar la escritura para el soporte y dónde ver lo que se hizo.

Crear una clave

1. Abre Configuraciones → Claves de API.
2. Haz clic en Crear clave.
3. En Identificación, completa el Nombre. Así aparece la clave en la lista y en la actividad.
4. Si quieres, completa la Finalidad: dónde y para qué se usa la clave.
5. En Permisos, elige una plantilla en Empieza por una plantilla. O haz clic en Empezar desde cero para marcar permiso por permiso.
6. En Vigencia, elige cuándo la clave Expira: Nunca, 30 días, 90 días, 1 año o Elegir fecha.
7. Haz clic en Crear clave.
8. En la ventana Clave creada, copia el secreto.
9. Haz clic en Ya lo copié.

La pantalla abre la página de la clave. En la ventana Clave creada, el bloque Prueba la clave trae un comando listo para comprobar que la clave funciona.

Dale a la clave solo lo que la integración necesita. Puedes ajustar los permisos después. Para una integración temporal, prefiere una vigencia.

Las plantillas de permisos

Cómo funcionan los permisos

Una política reúne permisos y dice Dónde se aplica:

• Toda la cuenta: la política se aplica en toda la cuenta.
• Productos específicos: la política se aplica en los productos elegidos y en todo lo que está dentro de ellos: módulos, clases, exámenes, certificados, comentarios y dudas.

Algunos permisos no pertenecen a un producto: alumnos, entregas, configuraciones. Si entran en una política restringida a productos, siguen valiendo en toda la cuenta. La pantalla avisa cuáles son.

Abierta, la política muestra los permisos por área: Alumnos, Contenido, Ventas, Atención, Área del alumno, Configuraciones, Integración y datos y Administración. Cada recurso tiene las columnas Leer, Crear, Editar y Eliminar y las Acciones especiales. Los botones Solo lectura, Todo y Nada marcan un área entera.

Atención: el área Administración tiene el sello Sensible. Una clave con esos permisos puede crear administradores y otras claves. Da esos permisos solo a integraciones de total confianza.

Otras marcas de la pantalla:

• Solo por administrador: una clave de API no concede este permiso. Solo un administrador lo concede a otro.
• Definida por la API: una integración definió el alcance de esta política. No la editas en esta pantalla. Sigue valiendo tal como está cuando publicas las otras.

Una clave puede tener más de una política. Agregar otra política suma una. Una clave sin ningún permiso se identifica, pero toda llamada a un recurso es rechazada. La pantalla avisa con Esta clave no tiene permisos.

Sin este paso, nada cambia. En la página de la clave, en la pestaña Permisos, un cambio solo vale después de Publicar cambios. Cada publicación crea una versión nueva, que vale a partir de la próxima llamada. Ver historial muestra las versiones en la pestaña Actividad.

La página de una clave

Haz clic en la fila para abrir la clave. La página tiene tres pestañas.

Resumen tiene cuatro paneles:

• Identificación: el nombre y la finalidad.
• Secreto: el Secreto actual (solo su final) y el botón Rotar.
• Uso: Último uso (la última llamada en los últimos 30 días), Entorno y Creada. El Entorno es Producción o Sandbox. La cuenta define el entorno cuando se crea la clave.
• Vigencia y límite: Expira y Llamadas por minuto. Vacío sigue el valor predeterminado de la cuenta. Un límite propio evita que una integración gaste el límite de las otras.

Los cambios del Resumen valen con Guardar ahora, en la barra inferior.

Permisos es el editor de políticas, con Publicar cambios.

Actividad muestra todo lo que se hizo con la clave en los últimos 30 días, con quién lo hizo y desde dónde: creación, ediciones, publicaciones de permisos, rotaciones, suspensión y revocación. El filtro Tipo separa Creación, Cambios, Secreto y Revocación.

Rotar, suspender, revocar

Las acciones están en el menú de la fila y en el encabezado de la página de la clave.

API antigua

La pestaña API antigua guarda lo que es de la API anterior:

• Token de identificación: el código que identifica tu plataforma cuando una integración lo pide.
• Claves de la API anterior: las claves antiguas, con nombre, código y fecha de creación. Siguen funcionando en las integraciones que ya las usan. No es posible crear claves nuevas aquí.

La única acción es eliminar. Eliminar una clave interrumpe al instante las integraciones que la usan. Para una integración nueva, crea una clave en la pestaña Claves.

Para tener en cuenta

Preguntas frecuentes