The Signup API allows coding agents and automation tools to create DeployHQ accounts programmatically. This is the only unauthenticated API endpoint.

## Create an account

    POST /api/v1/signup

### Required parameters

- `email` - Email address for the account administrator
- `password` - Password for the account (must meet Identity service requirements)

### Optional parameters

- `account_name` - Name for the account (used to generate the subdomain). If not provided, auto-generated from the email address (e.g., `dev@example.com` becomes `dev-example-com`).
- `full_name` - Full name of the account administrator (defaults to "{account_name} Admin")
- `package` - Billing package (defaults to `pro`). All accounts start with a trial period.
- `coupon` - Coupon code to apply to the new account
- `newsletter_opt_in` - Subscribe to the newsletter (true/false)
- `signup_source` - Identifier for the signup source (e.g., "claude-code", "cursor")
- `client` - Client identifier for tracking (e.g., "deployhq-cli", "mcp-server")
- `utm_params` - UTM tracking parameters as a JSON object

### Example request

```shell
curl -X POST https://deployhq.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "your-secure-password",
    "account_name": "my-company"
  }'
```

### Example response

```json
{
  "account": {
    "identifier": "billy-svc-abc123",
    "name": "My Company",
    "subdomain": "my-company",
    "url": "https://my-company.deployhq.com"
  },
  "api_key": "a1b2c3d4e5f6...",
  "ssh_public_key": {
    "id": "kp-abc123",
    "public_key": "ssh-ed25519 AAAA...",
    "fingerprint": "SHA256:..."
  },
  "oauth_urls": {
    "github": "https://github.com/login/oauth/authorize?...",
    "gitlab": "https://gitlab.com/oauth/authorize?...",
    "bitbucket": "https://bitbucket.org/site/oauth2/authorize?..."
  },
  "mcp_config": {
    "account": "my-company",
    "api_key": "a1b2c3d4e5f6...",
    "email": "developer@example.com"
  },
  "email_verified": false
}
```

### Using the returned credentials

After signup, use the returned `api_key` with the account email for HTTP Basic Authentication on all subsequent API calls:

```shell
curl -u developer@example.com:a1b2c3d4e5f6... \
  https://my-company.deployhq.com/projects.json \
  -H "Accept: application/json"
```

The `ssh_public_key` should be added to your repository hosting provider (GitHub, GitLab, Bitbucket) to allow DeployHQ to access your repositories. Visit the returned `oauth_urls` to connect your repository provider accounts.

### Email verification

Accounts are created immediately, but two gates remain in place until the administrator email is verified:

- The returned `api_key` will not authenticate any API request until the email is verified. Calls return 401 Unauthorized in the meantime.
- Deployments are blocked until verification, even if the API key authenticates by another path.

Check the `email_verified` field in the response to know the current state. A verification email is sent automatically on account creation; once the recipient clicks the link, both gates clear and the same `api_key` becomes active without any further action.

## Error responses

All error responses follow this format:

```json
{
  "status": "error",
  "errors": ["Description of the error"]
}
```

### Status codes

| Status | Meaning |
|--------|---------|
| 201 | Account created successfully |
| 400 | Missing or invalid parameters (email, password) |
| 401 | Email exists but password is incorrect |
| 403 | Account is temporarily locked due to too many failed attempts |
| 409 | Account name is not available (all subdomain variations exhausted) |
| 422 | Registration failed, or account has two-factor authentication enabled (must use web signup) |
| 429 | Too many signup attempts from this IP address (limit: 3 per hour) |
| 503 | Billing service temporarily unavailable |

## Rate limiting

The signup endpoint is limited to 3 requests per IP address per hour. If you exceed this limit, you will receive a 429 response. Wait and try again later.

## Post-signup next steps

1. Verify your email address using the link sent to your inbox
2. Connect a repository provider using the OAuth URLs
3. Create a project and configure servers
4. Start deploying