---
title: "Self-serve signup"
description: "Create a Bird account, organization, workspace, and access token with curl or the CLI by verifying an email code, then connect local MCP."
canonical: "https://bird.com/docs/ai/self-serve-signup"
---

# Self-serve signup

Most agents run against an account you already own: you [set up your agent](/docs/ai/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](#use-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. 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](/docs/ai/cli-for-agents) 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.

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

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

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

Confirm the credential works:

```bash
bird auth status   # authenticated: true, valid: true
```

The account is live and authenticated. The agent can now use the [CLI](/docs/ai/cli-for-agents) 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`.

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

### 1. Request a sign-in code

```bash
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:

```bash
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:

```bash
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:

```bash
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](/docs/ai/cli-for-agents) is the command contract the minted credential now unlocks.
- [MCP server](/docs/ai/mcp-server) connects local stdio MCP after CLI signup, or hosted MCP through OAuth.
- [Send your first email](/docs/get-started/send-your-first-email) is the happy path once the account exists.

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)