# Claves de API de AfterPack

Cómo crear, acotar, usar y revocar la clave que convierte un build local en un build Pro Cloud.

Source: https://www.afterpack.dev/es/docs/dashboard/api-keys

Una clave de API convierte un build local en un build **Pro Cloud**. Sin ella, [`npx afterpack@latest`](https://www.afterpack.dev/es/docs/cli#usage) y todos los [plugins](https://www.afterpack.dev/es/docs/frameworks) se ejecutan localmente con la protección [Free](https://www.afterpack.dev/es/docs/tiers) y no informan de nada. Con ella, los archivos del build van al motor en la nube de AfterPack, se miden contra tu espacio de trabajo y quedan registrados en el panel.

## Dónde viven las claves

Las claves viven dentro de un **proyecto**, en su página *Claves de API*: una clave está vinculada a un proyecto, y sus builds heredan ese proyecto, que agrupa bajo él los [builds](https://www.afterpack.dev/es/docs/dashboard/builds), los [Protection Maps](https://www.afterpack.dev/es/docs/protection-map) y el [uso](https://www.afterpack.dev/es/docs/dashboard/usage). En todo lo demás, una clave es una credencial de todo el espacio de trabajo: consume la asignación del espacio de trabajo y está sujeta al [rol en el espacio de trabajo](https://www.afterpack.dev/es/docs/dashboard/workspaces).

## Crear una

Solo los propietarios y administradores del espacio de trabajo pueden crear una clave, y solo desde el panel. Una clave no puede crear otra clave. El diálogo de creación pide:

- **Nombre** (obligatorio, hasta 100 caracteres): para qué sirve, por ejemplo *Pipeline de CI*. Es lo único que distinguirá las filas más adelante, así que ponle el nombre de lo que la va a usar.
- **Fecha de expiración** (opcional, en las opciones *avanzadas*): una fecha, que se fija al final del día en tu hora local. Una fecha pasada devuelve un error.
- **IPs permitidas** (opcional, en las opciones *avanzadas*): una lista separada por comas, por ejemplo `10.0.0.0/8, 203.0.113.7`.

> **La clave se muestra una sola vez**
>
> La clave en bruto se devuelve una vez y nunca se almacena; solo se guardan un hash y un prefijo corto no secreto. Cópiala antes de cerrar el diálogo. Si la pierdes, revócala y crea otra. No se puede volver a mostrar.

Las claves tienen la forma `ap_v1_` seguido de 40 caracteres aleatorios en base62, y la lista muestra solo el prefijo almacenado (`ap_v1_` más seis caracteres) con un `*`. Una clave atribuye los builds a su proyecto, pero no restringe a qué proyecto puede apuntar un build. [`scope.allowedProjects`](https://www.afterpack.dev/es/docs/cloud-api) devuelve un error.

## Usar una

El motor resuelve [`key`](https://www.afterpack.dev/es/docs/config#key) primero desde `--key=`, después desde el entorno y después desde `afterpack.json`. Define [`AFTERPACK_key`](https://www.afterpack.dev/es/docs/config#key) como secreto en tu [CI](https://www.afterpack.dev/es/docs/builds), o ponla en `afterpack.json` para una prueba local:

```json
{ "key": "ap_v1_..." }
```

Si no hay clave en ninguno de los dos sitios, el build se ejecuta localmente: el comportamiento por defecto y todo el recorrido del [nivel Free](https://www.afterpack.dev/es/docs/deployment-modes).

> **Una clave va en la CI, no en el repositorio**
>
> `afterpack.json` sirve para una prueba local, pero subirlo al repositorio publica una credencial que gasta la asignación de tu espacio de trabajo. Usa [`AFTERPACK_key`](https://www.afterpack.dev/es/docs/config#key) para cualquier cosa compartida. Consulta [Build y CI](https://www.afterpack.dev/es/docs/builds).

## La lista de claves

| Columna | Qué es |
| --- | --- |
| **Nombre** | Cómo la llamaste. |
| **Clave** | El prefijo almacenado que se muestra, `ap_v1_xxxxxx*`. |
| **Creada** | Cuándo se creó. |
| **Expira** | La fecha de expiración, o *Nunca*. |
| **Último uso** | La última vez que un build se autenticó con ella; útil para encontrar una clave que ya nada usa. |
| **Estado** | *Activa* o *Revocada*. |

## Rotar

No existe una rotación en el sitio. Rotar es siempre **crear la nueva y luego revocar la antigua**, y como una clave nunca expira por sí sola a menos que le pongas una fecha al crearla, las dos pueden convivir todo lo que dure el despliegue:

1. Crea la nueva clave.
2. Despliégala allí donde se usaba la antigua (secretos de CI, configuraciones de despliegue).
3. Confirma en la columna **Último uso** que los builds se autentican con ella.
4. Revoca la antigua.

## Revocar

Revocar es inmediato y no se puede deshacer: la clave deja de funcionar en la siguiente petición. La fila sigue visible, marcada como *Revocada*, en lugar de desaparecer, para que puedas ver para qué se usaba. Puede revocar una clave quien la creó y también cualquier administrador o propietario de su espacio de trabajo, así que una clave creada por alguien que ya se ha ido sigue pudiéndose revocar. Revocar es una acción del panel: una clave de API no puede revocar una clave, ni siquiera la suya. Si una clave se revoca a mitad de un build, la siguiente petición de la CLI con ella falla.

> **Si una clave se filtra, revócala**
>
> La revocación tiene efecto global en cuestión de segundos y es la solución completa: AfterPack nunca almacena la clave en bruto después de crearla, solo un id opaco, el prefijo no secreto y un hash con sal, así que no hay ninguna caché ni ningún log que limpiar después. Si no puedes acceder al panel, escribe a **security@afterpack.dev**.

## Límites con los que se ejecuta un build con clave

| | Límite |
| --- | --- |
| Peticiones por clave, por minuto | 10 en Free, 100 en un plan de pago |
| Peticiones por IP, por minuto | 100 |
| Bytes por archivo | 50 MB |
| Archivos por lote | 200 |
| Bytes por lote | 500 MB |

Un build que supera un límite [falla](https://www.afterpack.dev/es/docs/diagnostics#exit-codes) en lugar de recurrir a una salida sin ofuscar. Consulta [Cloud API](https://www.afterpack.dev/es/docs/cloud-api) para el protocolo y los códigos de error.

## Cuando los builds no aparecen

Casi siempre es una de estas causas:

1. **No se resolvió ninguna clave**: el build se ejecutó localmente. Comprueba que [`AFTERPACK_key`](https://www.afterpack.dev/es/docs/config#key) está definida donde se ejecuta el build.
2. **La clave está revocada o ha expirado**: la lista indica cuál de las dos.
3. **Estás mirando el proyecto equivocado**: el build se atribuye al proyecto de la clave, que puede no ser el que tienes abierto.

## Siguiente

- [Builds](https://www.afterpack.dev/es/docs/dashboard/builds): qué produce un build con clave.
- [Uso y facturación](https://www.afterpack.dev/es/docs/dashboard/usage): cuánto cuesta.
- [Cloud API](https://www.afterpack.dev/es/docs/cloud-api): el protocolo que autentica la clave.
- [Espacios de trabajo y proyectos](https://www.afterpack.dev/es/docs/dashboard/workspaces): los roles que controlan el acceso a esta página.