Cadastro self-service

A maioria dos agentes opera com uma conta que você já possui: você configura seu agente e ele entra pelo navegador. Este guia é o outro caminho, em que um agente sem conta cria uma por conta própria, inteiramente pelo terminal. Use a CLI ou o curl para verificar um endereço de e-mail e criar uma organização, um espaço de trabalho e uma credencial. O MCP stdio local requer uma credencial salva antes de iniciar; o MCP hospedado não expõe ferramentas de cadastro. Você precisa de acesso à caixa de entrada do e-mail para recuperar o código de verificação. Cadastros feitos pelo Bird CLI ou pelo servidor MCP são atribuídos à ferramenta que os realizou.

Use a CLI

Para os comandos CLI abaixo, você precisa da bird CLI instalada. O cadastro e a verificação são independentes de região e não exigem configuração inicial. No último passo, passe --region (us1 ou eu1) para create-org para escolher onde a conta e seus dados residem. Nenhum hostname ou variável de ambiente é necessário.

1. Solicite um código de login

bird auth signup envia por e-mail um código de login de seis dígitos. Verificar esse código cria a conta se o endereço de e-mail for novo. Ele usa o mesmo fluxo passwordless de magic-link do dashboard, então o código enviado por e-mail é tudo de que você precisa. Guarde o endereço de e-mail para o próximo passo.

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

2. Verifique o e-mail

O código de seis dígitos chega por e-mail, portanto vem de fora da CLI: leia-o na caixa de entrada. Passe-o com o mesmo e-mail para bird auth verify-email, que faz seu login e, para uma conta totalmente nova, retorna um onboarding_ticket de uso único.

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

3. Crie a organização

bird auth create-org consome o ticket para criar sua organização e espaço de trabalho e, em seguida, armazena a credencial gerada para que a CLI e o servidor stdio local MCP se autentiquem como a nova conta daqui em diante. É uma operação única: uma segunda chamada retorna 409. --region escolhe onde a conta e seus dados residem (us1 ou eu1) e roteia a chamada para essa região; a CLI deriva o host a partir dele, então você não precisa definir uma URL.

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

Confirme que a credencial funciona:

bird auth status   # authenticated: true, valid: true

A conta está ativa e autenticada. O agente agora pode usar a CLI para configurar canais e enviar mensagens.

Inspecione as entradas de CLI antes de executar

Cada passo é autodescritivo e não requer credencial, então um agente pode planejar toda a cadeia antes de enviar qualquer coisa. bird auth --help imprime o fluxo ordenado, --example imprime um corpo de solicitação pronto para editar e --response-schema imprime os campos que cada comando retorna.

Use curl

Você precisa de curl e jq, mas não de Bird CLI, conexão MCP, chave API ou sessão de navegador. Execute os comandos no mesmo shell, parando se uma solicitação falhar. Escolha us1 ou eu1 antes de começar; a solicitação de criação da organização deve ir para o host correspondente ao seu region.

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

O diretório privado contém a resposta de verificação e as credenciais. Mantenha esses arquivos fora do controle de versão, transcrições de chat e logs compartilhados.

1. Solicite um código de login

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 @-

Uma solicitação bem-sucedida retorna 204 sem corpo. Leia o código de seis dígitos no e-mail; ele expira após 15 minutos. A resposta não revela se a conta já existe.

2. Verifique o e-mail

Substitua 123456 pelo código recebido por e-mail. Salve a resposta sem imprimir o ticket de onboarding:

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

Continue somente se a verificação for bem-sucedida e a checagem do ticket encerrar com sucesso. Uma conta recém-verificada recebe um onboarding_ticket de uso único. Uma conta existente que já possui uma organização não precisa desse fluxo de cadastro; se a verificação exigir MFA, conclua o fluxo de login da conta existente.

3. Crie a organização e o espaço de trabalho

Escolha os nomes da organização e do espaço de trabalho, mantendo region alinhado com BIRD_BASE_URL. Essa solicitação usa o ticket, então nenhum cookie jar ou bearer token é necessário:

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"

Uma resposta bem-sucedida é 201 e contém organization, workspace, access_token, token_type e expires_in, além de um refresh token quando emitido. O access token expira após o número de segundos em expires_in. Armazene a resposta de forma segura. Essa é uma configuração única de conta; uma conta que já possui uma organização recebe 409.

4. Faça uma solicitação autenticada

Escreva o header bearer em um arquivo de configuração privado do curl e, em seguida, leia a identidade por trás da credencial:

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"

Uma resposta de identidade 200 confirma que a credencial funciona. Use o mesmo header bearer e o host regional para chamadas API subsequentes. O curl não instala credenciais na CLI nem em um cliente MCP; mova as credenciais salvas para o armazenamento de segredos da sua aplicação antes de remover o diretório temporário.

Próximos passos

• CLI para agentes é o contrato de comandos que a credencial gerada agora desbloqueia.
• Servidor MCP conecta MCP stdio local após o cadastro CLI, ou MCP hospedado via OAuth.
• Envie seu primeiro e-mail é o caminho principal assim que a conta existir.