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.
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.
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.
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.
bird auth create-org "Acme" --workspace-name "Production" --region us1 --onboarding-ticket "YOUR_ONBOARDING_TICKET" --accept-terms 2024-11-21Confirm the credential works:
bird auth status # authenticated: true, valid: trueThe 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.
umask 077
BIRD_SIGNUP_DIR=$(mktemp -d)
BIRD_REGION=us1
BIRD_BASE_URL="https://${BIRD_REGION}.platform.bird.com"
BIRD_EMAIL=you@example.comThe 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
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:
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/nullContinue 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:
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-21Replace 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.
Related resources
Continue with the documentation, guides and examples for this topic.