Self-serve signup · Docs

GitHub

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 or curl to verify an email address and create an organization, workspace, and credential. Local stdio MCP requires a saved credential before it can start; hosted MCP does not expose signup tools. You need access to the email inbox to retrieve the verification code.

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.

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

Code example

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

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.

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, but no Bird CLI, MCP connection, API key, or browser session. Run the commands in the same shell, stopping if a request fails. Choose us1 or eu1 before starting; the organization creation request must go to the host matching its region.

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 and credentials. Keep these files out of source control, chat transcripts, and shared logs.

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 and workspace

Choose your organization and workspace names, keeping region aligned with BIRD_BASE_URL. This request uses the ticket, so no cookie jar or bearer token is needed:

Code example

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"

A successful response is 201 and contains organization, workspace, access_token, token_type, and expires_in, plus a refresh token when issued. The access token expires after the number of seconds in expires_in. Store the response securely. This is one-time account setup; an account that already has an organization receives 409.

4. Make an authenticated request

Write the bearer header to a private curl configuration file, then read the identity behind the credential:

Code example

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"

A 200 identity response confirms that the credential works. Use the same bearer header and regional host for subsequent API calls. Curl does not install credentials into the CLI or an MCP client; move the saved credentials into your application's secret store before removing the temporary directory.

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.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideSetting up your coding agent Understand the conceptWhat is an MCP server, and how does an agent use one to send messages?Explore the capabilityCoding agents Follow the learning pathBuild with AI agents

Get an implementation brief