Autenticación y claves API

Cómo se autentican las solicitudes

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

await bird.email.send({
  from: "hello@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Hi",
  text: "Hello.",
});

import os

from bird import Bird

client = Bird(api_key=os.environ["BIRD_API_KEY"])

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Hi",
    text="Hello.",
)

client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
	log.Fatal(err)
}

_, err = client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Hi",
	Text:    "Hello.",
})

use MessageBird\Bird;

$bird = new Bird(getenv('BIRD_API_KEY') ?: '');

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Hi',
    text: 'Hello.',
);

export BIRD_API_KEY="bk_us1_..."

bird email send \
  --from hello@yourdomain.com \
  --to delivered@messagebird.dev \
  --subject Hi \
  --text Hello.

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "hello@yourdomain.com", "to": ["delivered@messagebird.dev"], "subject": "Hi", "text": "Hello." }'

Anatomía de una clave

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

• Prefijo: bk_{region}_ identifica el tipo de credencial y su región. El prefijo fijo y distintivo es lo que permite a los escáneres de secretos reconocer una clave Bird en el código, y el segmento de región dirige tu solicitud al host correcto.
• Payload: 23 caracteres aleatorios con 136 bits de entropía.
• Checksum: los últimos 6 caracteres son un checksum del resto de la clave, de modo que un SDK o la API pueden rechazar una clave mal escrita o truncada de inmediato, antes de buscarla.

Crear una clave

bird auth login --scope api_keys:write
bird api-keys create --body-file - <<'JSON'
{
  "name": "Email operations production key",
  "scopes": [{ "scope": "emails", "level": "write" }]
}
JSON

• Los alcances son editables. La edición reemplaza el conjunto de permisos y mantiene el mismo secreto. Puedes otorgar alcances que tu propia cuenta tenga. Si la clave se creó antes de que pudiera admitir un permiso como voice, rótala para añadir ese permiso. Las claves revocadas y las ya reemplazadas por rotación no se pueden editar.
• La expiración es fija. Configura expires_at cuando una clave deba dejar de funcionar en un momento conocido (el contrato de un colaborador, una ventana de migración). Pasado ese momento, la clave devuelve 401; una clave sin expiración funciona hasta que se revoque.
• La gestión de claves queda en manos de personas. Crear, editar y revocar claves requiere el permiso api_keys:write, que tienen los roles de administrador del espacio de trabajo y desarrollador (consulta Usuarios, equipos y roles) y que nunca se puede otorgar a una clave API. Una clave filtrada no puede crear más claves.

Alcances y niveles

Revocar una clave

Rotar una clave

bird auth login --scope api_keys:write
bird api-keys rotate key_01hqz8kp3v9x2m --yes

1. Crea una nueva clave con los mismos alcances.
2. Despliega la nueva clave en tus servicios.
3. Observa el last_used_on de la clave antigua hasta que el tráfico se haya movido.
4. Revoca la clave antigua.

Las claves pertenecen al espacio de trabajo

• Las claves sobreviven a las bajas. Cuando un empleado se va y su cuenta de usuario se elimina, las claves que creó siguen funcionando. Nunca tendrás una caída en producción porque la persona que hizo clic en "create" dejó la empresa. (Su salida sigue siendo un buen motivo para rotar las claves a las que tenía acceso.)
• El alcance de la clave se detiene en el espacio de trabajo. Nunca puede realizar operaciones a nivel de organización: facturación, miembros de la organización, configuración de la organización.

La ruta delegada: tokens OAuth para la CLI y el servidor MCP

Próximos pasos

• Referencia de autenticación: semántica de encabezados de solicitud y respuestas de error
• Regiones: hosts regionales y enrutamiento
• Usuarios, equipos y roles: quién puede gestionar claves
• Espacio de trabajo: el espacio de trabajo al que se vincula una clave