# Claves de API

> La credencial que otro sistema usa para leer y cambiar datos de tu plataforma por la API: crear la clave, dar permisos, guardar el secreto y revocar.

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í](/es/conta/acesso-do-suporte-da-cademi) 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

| Plantilla | Lo que concede |
|---|---|
| **Solo lectura** | Lee todo, no cambia nada |
| **Gestión de contenido** | Productos, clases, vitrinas y banners |
| **Gestión de alumnos** | Alumnos, matrículas, etiquetas y progreso |
| **Ventas y matrículas** | Entregas, eventos de venta y accesos |
| **Configuración** | Configuraciones, correos, código personalizado y campos del perfil |
| **Acceso total** | Todo, excepto administradores y claves |

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

| Acción | Lo que hace | ¿Se puede deshacer? |
|---|---|---|
| **Rotar secreto** | Genera un secreto nuevo. En **El secreto actual deja de funcionar en**, elige **1 hora**, **24 horas**, **3 días** o **7 días**. Hasta entonces, los dos secretos funcionan, y cambias el secreto en las integraciones sin interrupción. El nuevo aparece una vez, en **Secreto nuevo** | Después del plazo, el secreto anterior no vuelve |
| **Suspender** | La clave es rechazada en toda llamada, pero sigue registrada | Sí, con **Reactivar** |
| **Revocar** | La clave deja de funcionar al instante, en todas las integraciones. Ya no se puede cambiar. La pestaña **Actividad** sigue disponible | No. Para integrar de nuevo, crea otra clave |
| **Quitar de la lista** | Quita de la lista una clave **Revocada** o **Expirada**. Lo que hizo sigue registrado en la actividad de la cuenta | No |

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

- **El secreto no vuelve.** Si la integración perdió el secreto, la pantalla no lo muestra de nuevo. Usa **Rotar secreto** y cambia el secreto en la integración dentro del plazo elegido.
- **Expiró, se detuvo.** Después de la fecha de vigencia, la clave deja de funcionar sola y aparece como **Expirada**. Para seguir con la misma integración, crea una clave nueva.
- **Sandbox.** El entorno de una clave es el de la cuenta en que se creó. Una cuenta de pruebas genera claves de **Sandbox**, que no acceden a los datos de producción.
- **Quién puede cambiarlas.** Ver las claves es un permiso del administrador. Crear, cambiar o revocar es otro. Un administrador que solo ve no puede crear.
- **Actividad por 30 días.** La pestaña **Actividad** guarda los últimos 30 días. El registro general de la cuenta guarda lo que hizo la clave, incluso después de que sale de la lista.

## Preguntas frecuentes

**La integración dejó de funcionar de repente.** Revisa tres cosas:

1. El **Estado** de la clave: suspendida, expirada o revocada.
2. Si alguien rotó el secreto y el plazo del anterior ya pasó.
3. Si los permisos publicados cubren lo que hace la integración.

La pestaña **Actividad** muestra quién cambió qué.

**¿Puedo dar una clave que solo vea un producto?** Sí. En la política, elige **Productos específicos**. Los permisos que no son de producto (alumnos, entregas, configuraciones) siguen valiendo en toda la cuenta, y la pantalla avisa cuáles son.

**¿Cuál es la diferencia entre suspender y revocar?** Suspender es temporal: la clave queda rechazada hasta que la reactives. Revocar es definitivo.

**Cambié los permisos y la integración sigue sin acceso.** El cambio solo vale después de **Publicar cambios**, en la pestaña **Permisos**.