Registro autoservicio

La mayoría de los agentes se ejecutan contra una cuenta que ya tienes: configuras tu agente y este inicia sesión a través del navegador. Esta guía es la otra ruta, donde un agente que no tiene cuenta crea una por sí mismo, completamente desde la terminal. Usa CLI o curl para verificar una dirección de correo electrónico y crear una organización, un espacio de trabajo y una credencial. El MCP stdio local requiere una credencial guardada antes de poder iniciarse; el MCP alojado no expone herramientas de registro. Necesitas acceso a la bandeja de entrada del correo para obtener el código de verificación. Los registros realizados a través del Bird CLI o del servidor MCP se atribuyen a la herramienta que los realizó.

Usa la CLI

Para los comandos de la CLI a continuación, necesitas la bird CLI instalada. El registro y la verificación son independientes de la región y no requieren configuración inicial. En el último paso, pasa --region (us1 o eu1) a create-org para elegir dónde residen la cuenta y sus datos. No se necesitan nombres de host ni variables de entorno.

1. Solicita un código de inicio de sesión

bird auth signup envía por correo un código de inicio de sesión de seis dígitos. Verificar ese código crea la cuenta si la dirección de correo es nueva. Usa la misma vía de enlace mágico sin contraseña que el panel, así que el código enviado por correo es todo lo que necesitas. Conserva la dirección de correo para el siguiente paso.

Ejemplo de código

bird auth signup you@example.com
# { "email": "you@example.com", "status": "code_sent" }

2. Verifica el correo electrónico

El código de seis dígitos llega por correo electrónico, así que proviene de fuera de la CLI: léelo de la bandeja de entrada. Pásalo junto con el mismo correo a bird auth verify-email, que inicia tu sesión y, para una cuenta nueva, devuelve un onboarding_ticket de un solo uso.

Ejemplo de código

bird auth verify-email you@example.com --code 123456
# { "onboarding_ticket": "...", "user_id": "usr_..." }

3. Crea la organización

bird auth create-org consume el ticket para crear tu organización y espacio de trabajo, y luego almacena la credencial generada para que la CLI y el servidor stdio MCP local se autentiquen como la nueva cuenta de aquí en adelante. Es de un solo uso: una segunda llamada devuelve 409. --region elige dónde residen la cuenta y sus datos (us1 o eu1) y enruta la llamada a esa región; la CLI deriva el host a partir de ese valor, así que no necesitas establecer una URL.

Ejemplo de código

bird auth create-org "Acme" --workspace-name "Production" --region us1 --onboarding-ticket "YOUR_ONBOARDING_TICKET"

Confirma que la credencial funciona:

Ejemplo de código

bird auth status   # authenticated: true, valid: true

La cuenta está activa y autenticada. El agente ahora puede usar la CLI para configurar canales y enviar mensajes.

Inspecciona las entradas de CLI antes de ejecutar

Cada paso se describe a sí mismo y no necesita credencial, así que un agente puede planificar toda la cadena antes de enviar nada. bird auth --help imprime el flujo ordenado, --example imprime un cuerpo de solicitud listo para editar y --response-schema imprime los campos que devuelve cada comando.

Usa curl

Necesitas curl y jq, pero no Bird CLI, conexión MCP, clave API ni sesión de navegador. Ejecuta los comandos en la misma shell, deteniéndote si una solicitud falla. Elige us1 o eu1 antes de empezar; la solicitud de creación de organización debe ir al host que corresponda a su region.

Ejemplo de código

umask 077
BIRD_SIGNUP_DIR=$(mktemp -d)
BIRD_REGION=us1
BIRD_BASE_URL="https://${BIRD_REGION}.platform.bird.com"
BIRD_EMAIL=you@example.com

El directorio privado contiene la respuesta de verificación y las credenciales. Mantén estos archivos fuera del control de código fuente, transcripciones de chat y registros compartidos.

1. Solicita un código de inicio de sesión

Ejemplo de código

jq -n --arg email "$BIRD_EMAIL" '{email: $email}' |
  curl --fail-with-body --silent --show-error \
    "$BIRD_BASE_URL/v1/auth/magic-link" \
    -H 'Content-Type: application/json' --data-binary @-

Una solicitud exitosa devuelve 204 sin cuerpo. Lee el código de seis dígitos del correo electrónico; expira después de 15 minutos. La respuesta no revela si la cuenta ya existe.

2. Verifica el correo electrónico

Reemplaza 123456 con el código recibido por correo. Guarda la respuesta sin imprimir su ticket de incorporación:

Ejemplo de código

BIRD_CODE=123456
jq -n --arg email "$BIRD_EMAIL" --arg code "$BIRD_CODE" \
  '{email: $email, code: $code}' |
  curl --fail-with-body --silent --show-error \
    "$BIRD_BASE_URL/v1/auth/magic-link/verify-code" \
    -H 'Content-Type: application/json' --data-binary @- \
    --output "$BIRD_SIGNUP_DIR/verified.json"
jq -e '.onboarding_ticket | type == "string" and length > 0' \
  "$BIRD_SIGNUP_DIR/verified.json" > /dev/null

Continúa solo si la verificación tiene éxito y la comprobación del ticket finaliza correctamente. Una cuenta nueva verificada recibe un onboarding_ticket de un solo uso. Una cuenta existente con organización no necesita este flujo de registro; si la verificación requiere MFA, completa el flujo de inicio de sesión de la cuenta existente.

3. Crea la organización y el espacio de trabajo

Elige los nombres de tu organización y espacio de trabajo, manteniendo region alineado con BIRD_BASE_URL. Esta solicitud usa el ticket, por lo que no se necesita jar de cookies ni token bearer:

Ejemplo de código

jq -n --arg region "$BIRD_REGION" \
  --slurpfile verified "$BIRD_SIGNUP_DIR/verified.json" \
  '{org_name: "Acme", workspace_name: "Production", region: $region,
    onboarding_ticket: $verified[0].onboarding_ticket}' |
  curl --fail-with-body --silent --show-error \
    "$BIRD_BASE_URL/v1/auth/onboarding" \
    -H 'Content-Type: application/json' --data-binary @- \
    --output "$BIRD_SIGNUP_DIR/account.json"

Una respuesta exitosa es 201 y contiene organization, workspace, access_token, token_type y expires_in, más un token de actualización cuando se emite. El token de acceso expira después del número de segundos en expires_in. Almacena la respuesta de forma segura. Esta es una configuración de cuenta de un solo uso; una cuenta que ya tiene organización recibe 409.

4. Haz una solicitud autenticada

Escribe el encabezado bearer en un archivo de configuración privado de curl y luego lee la identidad detrás de la credencial:

Ejemplo de código

jq -er '.access_token | select(type == "string" and length > 0) |
  "header = \"Authorization: Bearer \(.)\""' \
  "$BIRD_SIGNUP_DIR/account.json" > "$BIRD_SIGNUP_DIR/curl-auth.conf"
curl --fail-with-body --silent --show-error \
  --config "$BIRD_SIGNUP_DIR/curl-auth.conf" "$BIRD_BASE_URL/v1/auth/me"

Una respuesta de identidad 200 confirma que la credencial funciona. Usa el mismo encabezado bearer y host regional para las llamadas API posteriores. Curl no instala credenciales en la CLI ni en un cliente MCP; mueve las credenciales guardadas al almacén de secretos de tu aplicación antes de eliminar el directorio temporal.

Próximos pasos

CLI para agentes es el contrato de comandos que la credencial generada ahora desbloquea.
El servidor MCP conecta MCP stdio locales después del registro con CLI, o MCP alojados a través de OAuth.
Envía tu primer correo electrónico es la ruta directa una vez que la cuenta existe.

Continúa con la documentación, guías y ejemplos de este tema.

Obtener un resumen de implementación

Recursos relacionados