Gestión de claves API
Una clave API es una credencial de aplicación. Pertenece a tu espacio de trabajo, y una aplicación que la posea puede llamar a Bird API dentro de los alcances asignados. Puedes gestionar claves en el dashboard o a través de API. Para el contrato técnico completo, consulta Authentication & claves API.
Dónde se encuentran las claves
Abre Claves API, fijado cerca del final de la barra lateral junto a Webhooks y Logs. La página lista el nombre de cada clave, el prefijo enmascarado, los alcances, el estado, la expiración y la fecha de último uso.
Crear, editar y revocar claves requiere el rol de espacio de trabajo adecuado: los roles Admin y Developer lo tienen. Consulta Users, teams & roles.
Crear una clave
- En la página de claves API, elige crear una nueva clave.
- Nómbrala según su función, por ejemplo "Billing service production,", en lugar de usar el nombre de una persona.
- Elige los alcances. Cada alcance tiene un nivel read o write. Otorga solo los alcances y niveles que la aplicación necesite.
- Crea la clave y copia el secreto de inmediato.
El secreto se muestra una sola vez
La clave completa aparece una sola vez, cuando la creas o la rotas. Bird no puede volver a mostrar el secreto. Cópialo directamente a un gestor de secretos o a la configuración de despliegue. Si lo pierdes, rota o reemplaza la clave.
Edita los alcances de una clave desde su fila en la página de claves API. La edición reemplaza el conjunto de permisos y conserva el mismo secreto. Es posible que necesites rotar una clave antigua para añadir un permiso. Consulta Authentication & claves API para las restricciones de alcance.
Revocar una clave
Revoca una clave cuando ya no la necesites o sospeches que se filtró. La revocación es permanente. La validación de claves usa una caché de corta duración, por lo que una clave revocada puede seguir funcionando hasta cinco segundos antes de que las solicitudes fallen en la autenticación.
Si sospechas que una clave se filtró, revócala y despliega un reemplazo. Las solicitudes fallarán hasta que la aplicación use una clave activa.
Para rotar sin tiempo de inactividad, usa la acción de rotación y mantén su período de gracia predeterminado de 24 horas. Despliega el reemplazo antes de que el período de gracia termine. Establece un período de gracia más corto solo cuando puedas actualizar los clientes antes.
Todo queda registrado
La creación de claves, las ediciones de alcance, la rotación y la revocación aparecen en el registro de auditoría de tu organización. Una edición de alcance registra los alcances añadidos y eliminados. Incluye las claves revocadas en la lista de claves para revisar sus metadatos.
Buenas prácticas
- Usa una clave por aplicación y entorno. Separa las claves de staging y producción para poder revocar una sin afectar la otra.
- Vigila la columna de último uso. Revoca las claves inactivas que ya no necesites.
- Nunca pongas claves en código del lado del cliente ni en repositorios públicos. Las claves pertenecen únicamente a la configuración del servidor y a gestores de secretos.
Próximos pasos
- Authentication & claves API: anatomía de claves, detalles de alcance y el contrato API
- Registro de auditoría: revisión de eventos de creación y revocación de claves
- Users, teams & roles: quién puede gestionar claves
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.