Autenticación
Cada solicitud a la API se autentica con una clave API enviada como bearer token en el encabezado Authorization:
curl https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."Las claves tienen alcance de espacio de trabajo: una clave se autentica como tu espacio de trabajo, lleva los alcances elegidos al crearla y solo puede acceder a los recursos de ese espacio de trabajo. En la Guía de autenticación y claves API se explica cómo crear, definir alcances, rotar y revocar claves: créalas en el dashboard en Platform tools > API keys, o sin navegador con bird api-keys create. Esta página describe el contrato a nivel de protocolo.
Formato de la clave
Una clave empieza por bk_{region}_, que indica la región donde se creó. Las claves bk_us1_ solo son válidas contra https://us1.platform.bird.com, y las claves bk_eu1_ solo contra https://eu1.platform.bird.com. Los SDK oficiales y el CLI usan este prefijo para seleccionar el host.
La clave completa se devuelve exactamente una vez, en la respuesta que la crea. El texto plano no se puede recuperar de nuevo, y el dashboard solo muestra un key_prefix corto (los primeros 15 caracteres). Si pierdes una clave, revócala y reemplázala.
Respuestas de error
Todos los errores usan la respuesta de error estándar.
| Estado | Cuándo |
|---|---|
401 | Falta el encabezado Authorization, la clave tiene un formato incorrecto o es desconocida, o la clave fue revocada. |
403 | La clave es válida pero no tiene el alcance que requiere el endpoint. |
421 | La región de la clave no coincide con el host, por ejemplo una clave bk_eu1_... enviada a us1.platform.bird.com. |
El cuerpo 421 Misdirected Request (tipo de error misdirected_error, código E01010) indica el host regional correcto, para que el cliente pueda detectar el error y reenviar sin conjeturas. Consulta URLs base y regiones.
Las sesiones del dashboard no son claves API
El dashboard de Bird no usa claves API: una persona que inicia sesión obtiene una cookie de sesión, con alcance limitado a sus propios permisos de usuario. Las cookies de sesión no se aceptan en la superficie programática API, y las claves API no se aceptan en el dashboard. Las cargas de trabajo de servidor siempre usan claves API.
Relacionado
- Guía de autenticación y claves API: crear, definir alcances, rotar y revocar claves
- URLs base y regiones: hosts regionales y el modelo de regiones
- Errores: la respuesta de error y el catálogo
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.