Autenticación
El formato de las claves, dónde guardarlas, las restricciones por clave, la rotación y qué hacer si una clave se filtra.
Cada solicitud a la API lleva una clave de API en la cabecera Authorization:
Authorization: Bearer sk-popnow-3f9c0a…No hay otra forma de autenticarse: las claves en la query string de la URL nunca se aceptan y tu sesión de popnow.ai no sirve en la API.
Una excepción: las rutas compatibles con OpenAI bajo /v1 también leen la clave de la cabecera x-api-key, así que los clientes al estilo OpenAI funcionan sin cambios. Las rutas nativas /api/v1 solo leen Authorization.
Cómo es una clave
Una clave es sk-popnow- seguido de 48 caracteres hexadecimales en minúsculas. Después de crearla, la consola de la API solo muestra los primeros caracteres, así que una clave perdida no se puede recuperar: crea una nueva.
Crea una clave
- Inicia sesión en popnow.ai y abre la consola de la API.
- Elige Create key y ponle un nombre que diga dónde va a vivir, como
production-backend. - Cópiala enseguida. Solo se muestra una vez.
Puedes tener varias claves a la vez. Una por entorno o por servicio es buena costumbre, porque así puedes revocar una sin tocar las demás. Todas gastan del mismo saldo de créditos.
Dónde guardarla
- En una variable de entorno o en el almacén de secretos de tu plataforma (
POPNOW_API_KEY), no en el código. - Nunca en un navegador, una app móvil ni ningún código que se ejecute en el dispositivo de otra persona. Quien pueda leer la clave puede gastar tus créditos. Pon tu propio servidor en medio y deja que él llame a PopNow.
- Tampoco en los logs. Si registras las cabeceras de las solicitudes, quita antes
Authorization.
Limita lo que puede hacer una clave
Cada clave puede tener sus propios límites, configurados en la consola de la API:
| Restricción | Qué hace | Error cuando bloquea una solicitud |
|---|---|---|
| Modelos permitidos | La clave solo puede llamar a los modelos de la lista | 40301 |
| Lista de IP permitidas | Las solicitudes deben venir de estas direcciones o rangos | 40302 |
| Topes de gasto | Límites diario, mensual y total para esta clave, en créditos | 40202 |
Por defecto una clave no tiene restricciones ni topes. Da a las claves de producción el alcance más pequeño que funcione.
Las tareas pertenecen a la clave que las creó
recordInfo, retry, purge, la lista de tareas y el uso solo ven las tareas creadas con la misma clave. Una tarea creada con otra clave de tu cuenta responde 404, igual que una tarea que no existe. Las generaciones que inicias en la web tampoco las ve ninguna clave. Para ver toda la cuenta, usa la consola de la API.
Rotación
Para cambiar una clave sin cortes:
- Crea la clave nueva.
- Despliégala en todos los sitios donde se usaba la antigua.
- Comprueba en la consola que la última vez que se usó la antigua deja de moverse.
- Revoca la clave antigua.
Si una clave se filtra
- Revócala ya en la consola de la API. El cambio aplica desde la siguiente solicitud.
- Crea una de reemplazo y despliégala.
- Revisa para qué se usó: los logs y el uso de la consola muestran cada tarea que creó esa clave.
- Restringe la nueva con una lista de IP permitidas y un tope de gasto.
Si ves gastos que no hiciste tú, contacta con soporte.
Cómo se ve un fallo
Los tres problemas de autenticación devuelven HTTP 401 con code: 401; msg los distingue:
msg dice | Qué pasó | Qué hacer |
|---|---|---|
| Faltan credenciales | No llegó ninguna cabecera Authorization | Comprueba que la cabecera está puesta y que el proceso en ejecución cargó la variable de entorno |
| Formato de clave no reconocido | Llegó algo, pero no es una clave de PopNow | Asegúrate de que empieza por sk-popnow-; puede que pegaras otra cosa |
| Credenciales no válidas o caducadas | La clave no existe, se revocó o caducó | Crea una clave nueva; reintentar nunca funcionará |
Una clave válida también puede recibir 403, por ejemplo si el correo de la cuenta aún no está verificado (40310). Mira Errores.