Un emisor programado debe seguir funcionando cuando el empleado que lo configuró se va. Una herramienta que actúa en nombre de ese empleado necesita un acceso que siga sus permisos.
Elige la credencial en función de esa titularidad. Mantén cualquiera de las dos credenciales fuera del código del navegador y de los registros, porque cualquiera que la tenga puede intentar solicitudes autenticadas.
¿Qué me permite hacer cada credencial?
Una clave API actúa en nombre de un espacio de trabajo. Un token OAuth permite a una herramienta autorizada actuar en nombre de una persona.
Las claves Bird API comienzan con bk_. Sus permisos pertenecen al espacio de trabajo, así que eliminar al creador no las invalida. Otorga solo los alcances que el servicio necesita para limitar lo que una clave expuesta puede hacer.
Una clave no puede realizar operaciones a nivel de organización, como gestionar miembros de la organización o la facturación. Añadir más alcances de espacio de trabajo no elimina esa restricción.
Cuando inicias sesión a través del servidor CLI o MCP, autorizas a una herramienta con un subconjunto de tus permisos. La herramienta recibe un token bt_ de corta duración. Ella gestiona la renovación del token, así que no copies ese token en el gestor de secretos de un servicio.
Revoca una herramienta autorizada desde Profile > Connected apps. Usa autenticación para elegir alcances y distinguir claves de espacio de trabajo de concesiones personales.
¿Cómo roto una clave API?
Emite un reemplazo y despliégalo antes de que termine el solapamiento de la clave antigua.
Puedes rotar desde el panel, con bird api-keys rotate, o a través de la herramienta api_keys_rotate MCP. La rotación CLI y MCP requiere una concesión personal con api_keys:write. Una clave API no puede tener ese permiso ni rotar otra clave.
La rotación devuelve el token del reemplazo una sola vez. Guárdalo de inmediato porque lecturas posteriores no pueden recuperarlo. El reemplazo conserva el nombre anterior y las restricciones de IP. También conserva los permisos, a menos que proporciones nuevos scopes.
Configura grace_period para controlar el solapamiento. Su valor predeterminado es 24h, así que completa el despliegue dentro de ese día. Una expiración anterior en la clave antigua sigue aplicándose. La rotación nunca la extiende.
Usa grace_period: "0" cuando una clave filtrada deba revocarse de inmediato. La validación en caché aún puede aceptarla brevemente, como se describe más abajo.
- Solicita la rotación y guarda el token devuelto.
- Despliega el reemplazo en cada servicio antes de que termine el solapamiento.
- Confirma solicitudes exitosas con el reemplazo a través de los registros del servicio.
- Deja que la clave antigua expire, o revócala cuando el cambio esté completo.
La referencia de rotación cubre el comando y sus opciones.
¿Qué puede salir mal durante la rotación?
Una respuesta perdida puede dejarte con un reemplazo emitido cuyo token nunca guardaste.
Usa la misma Idempotency-Key al reintentar la solicitud de rotación para que Bird pueda reproducir su respuesta. Una clave solo puede rotarse una vez. Sin la misma clave de idempotencia, repetir la rotación devuelve 409. Rota el reemplazo para un cambio planificado posterior.
Una clave revocada no puede rotarse. Crea una clave nueva si la original ya fue revocada.
El reemplazo no tiene expiración, incluso cuando la original sí la tenía. No puedes añadir una expiración después. Crea una clave nueva con expires_at cuando deba dejar de funcionar en un momento conocido.
Para un despliegue con duración incierta, crea una segunda clave y gestiona el solapamiento tú mismo. Despliégala antes de revocar la original. El periodo de gracia de una rotación no puede extenderse después de la solicitud.
¿Qué tan rápido surte efecto la revocación?
Una clave revocada puede seguir siendo aceptada durante un máximo de cinco segundos mientras la validación en caché expira.
Trata una clave expuesta como utilizable durante toda esa ventana. La revocación es permanente, así que una clave revocada no puede reactivarse. Bird conserva su registro para auditoría.
Usa key_prefix o fingerprint para identificar una clave en conversaciones con soporte. Nunca incluyas la credencial completa, porque esos identificadores son suficientes para distinguirla sin conceder acceso.
¿Qué credencial debo elegir?
Elige según quién es el titular de la carga de trabajo y qué permisos necesita.
- Clave API: un servicio que debe seguir funcionando de forma independiente de su creador.
- Concesión OAuth: un CLI o agente que actúa dentro de los permisos de una persona.
- Rotación: una clave de reemplazo que puedes desplegar durante un solapamiento conocido.
- Clave nueva con expiración: una credencial que debe dejar de funcionar en un momento específico.
En resumen
Las credenciales de servicio pertenecen al espacio de trabajo.
Una clave sobrevive a la salida de su creador. Una herramienta que usa OAuth actúa dentro de los permisos de la persona que la autorizó.
Despliega durante el solapamiento de la rotación.
La clave antigua sigue funcionando durante 24 horas de forma predeterminada, salvo que su expiración existente llegue antes.
Guarda el reemplazo cuando se emite.
La rotación devuelve el nuevo token una sola vez. Mantén la misma clave de idempotencia si reintentas la solicitud de rotación.
La revocación tiene una ventana de propagación corta.
La validación en caché puede aceptar una clave revocada durante un máximo de cinco segundos, así que ten en cuenta ese retraso tras una filtración.