Autenticación

Cada solicitud a la API se autentica con una clave API enviada como bearer token en el encabezado Authorization:

Ejemplo de código

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 en su creación y solo puede acceder a sus recursos. Cómo crear, definir alcances, rotar y revocar claves se explica en la Guía de autenticación y claves API: créalas en el dashboard en Developers > Claves API, o sin navegador con bird api-keys create. Esta página cubre el contrato a nivel de protocolo.

Formato de la clave

Ejemplo de código

bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix

Una clave es bk_{region}_{payload}{checksum}:

bk_{region}_: El prefijo identifica el tipo de credencial y la región donde se creó la clave. 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. El prefijo fijo bk_ está registrado en GitHub secret scanning, por lo que una clave Bird filtrada en un repositorio público se detecta y se reporta.
Payload: Una cadena aleatoria larga con más de 128 bits de entropía.
Checksum: Los últimos 6 caracteres son un checksum del resto de la clave, lo que permite al cliente rechazar localmente una clave mal escrita o truncada antes de hacer cualquier solicitud.

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 12 caracteres). Revoca y reemplaza una clave perdida.

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 sobre este tema. Los recursos están en inglés.

Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first email

Obtener un resumen de implementación