Sign inGet Started

Self-serve signup

Most agents run against an account you already own: you set up your agent and it signs in through the browser. This guide is the other path, where an agent that has no account creates one itself, entirely from the terminal. Use the CLI to verify an email address, accept the Terms, and create an organization, workspace, and credential; the email steps also work with curl. MCP cannot do this first signup: local stdio MCP (bird mcp) starts only when a credential is already in place, and hosted MCP has no signup tools. You need access to the email inbox to retrieve the verification code. Signups through the Bird CLI or MCP server are attributed to the tool that made them.

Use the CLI

For the CLI commands below, you need the bird CLI installed. Signup and verification are region-agnostic and require no initial configuration. At the last step, pass --region (us1 or eu1) to create-org to choose where the account and its data live. No hostnames or environment variables are required.

1. Request a sign-in code

bird auth signup emails a six-digit sign-in code. Verifying that code creates the account if the email address is new. It uses the same passwordless magic-link path as the dashboard, so the emailed code is all you need. Keep the email address for the next step.

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

2. Verify the email

The six-digit code arrives by email, so it comes from outside the CLI: read it from the inbox. Pass it with the same email to bird auth verify-email, which signs you in and, for a brand-new account, returns a single-use onboarding_ticket.

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

3. Read the Terms

bird auth terms returns the current version of Bird's Terms of Service and the address of its page. Show that page to the person who will own the organization, and ask whether they accept the Terms on its behalf.

Code example
bird auth terms
# { "version": "2024-11-21", "url": "https://bird.com/legal/terms-2024-11-21", ... }

4. Create the organization

bird auth create-org consumes the ticket to create your organization and workspace, then stores the minted credential so the CLI and the local stdio MCP server authenticate as the new account from here on. It is one-time: a second call returns 409. --region chooses where the account and its data live (us1 or eu1) and routes the call to that region; the CLI derives the host from it, so you do not set a URL.

--accept-terms records that the owner accepted that Terms version on behalf of the organization. Pass it only after they agree, with the version that step 3 returned. Without it, the command returns E02100 when acceptance is required; the ticket stays valid, so read the Terms and retry.

Code example
bird auth create-org "Acme" --workspace-name "Production" --region us1 --onboarding-ticket "YOUR_ONBOARDING_TICKET" --accept-terms 2024-11-21

Confirm the credential works:

Code example
bird auth status   # authenticated: true, valid: true

The account is live and authenticated. The agent can now use the CLI to configure channels and send messages.

This credential holds every permission the new organization's owner can delegate, organization billing included, and signup shows no consent screen to narrow it. Before an agent runs unattended, create a scoped API key for it: Agent controls shows how.

Inspect CLI inputs before you run

Every step is self-describing and needs no credential, so an agent can plan the whole chain before sending anything. bird auth --help prints the ordered flow, --example prints a ready-to-edit request body, and --response-schema prints the fields each command returns.

Use curl

You need curl and jq for the email steps, and the bird CLI to create the organization. No MCP connection, API key, or browser session is needed. Run the commands in the same shell, stopping if a request fails. Choose us1 or eu1 before starting.

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

The private directory holds the verification response, which carries the onboarding ticket. Keep it out of source control, chat transcripts, and shared logs.

1. Request a sign-in code

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

A successful request returns 204 with no body. Read the six-digit code from the email; it expires after 15 minutes. The response does not reveal whether the account already exists.

2. Verify the email

Replace 123456 with the emailed code. Save the response without printing its onboarding ticket:

Code example
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 only if verification succeeds and the ticket check exits successfully. A new verified account receives a single-use onboarding_ticket. An existing account with an organization does not need this signup flow; if verification requires MFA, complete the existing account's sign-in flow instead.

3. Create the organization

Creating the organization records the owner's acceptance of the Terms, so it runs through the CLI. Read the Terms with bird auth terms, show the page to the person who will own the organization, and once they agree, pass the saved ticket to bird auth create-org:

Code example
bird auth terms
bird auth create-org "Acme" --workspace-name "Production" --region "$BIRD_REGION" \
  --onboarding-ticket "$(jq -r .onboarding_ticket "$BIRD_SIGNUP_DIR/verified.json")" \
  --accept-terms 2024-11-21

Replace 2024-11-21 with the version that bird auth terms returns. The CLI stores the minted credential, so remove the temporary directory afterwards.

Next steps

  • CLI for agents is the command contract the minted credential now unlocks.
  • MCP server connects local stdio MCP after CLI signup, or hosted MCP through OAuth.
  • Send your first email is the happy path once the account exists.
  • Agent controls covers the scoped key, destination allowlist, and spend limits to set before an agent runs unattended.