---
title: "Create an account and API key in one call"
method: POST
path: "/agents/register"
tags: ["Account"]
---

# Create an account and API key in one call

`POST /agents/register`

## Request

- Base URL: `https://barevalue.com/api/v1`
- URL: `https://barevalue.com/api/v1/agents/register`
- Auth: none required

For AI agents. Returns a working API key in this one call: no password and no email click before the first order. Send the email address of the person you are acting for; they receive a verification link. An address that already has an account is refused (`registration_failed`): its owner makes a key under Settings, API Keys. Until the address is verified the account is limited to a small free allowance (see `allowance`). Limits: 30 requests per hour and 20 accounts per day per IP.

## Request body

- AgentRegisterRequest
  - `email` string, email, required: Email address of the person the account is for
  - `first_name` string
  - `last_name` string
  - `agent_name` string: Name of the agent or app creating the account
  - `ref` string: Optional code of the listing or link the agent came from, as printed in that listing's install instructions (e.g. `docker`). Lowercase letters, digits and hyphens. A value of any other shape is ignored and never causes a refusal. Also read from `?ref=` on the request address.

## Response `201`

Account created and API key issued

- AgentRegisterResponse
  - `api_key` string: Shown once. Send as `Authorization: Bearer <api_key>`.
  - `key_prefix` string
  - `message` string
  - `account` object
    - `id` integer
    - `email` string
    - `email_verified` boolean
    - `credit_balance` number
  - `allowance` AgentAllowance: Limits on an account whose email is not verified yet. `limited` is false once verified.
    - `limited` boolean, required
    - `reason` string
    - `minutes_remaining` number
    - `orders_remaining` integer
    - `minutes_limit` integer
    - `orders_limit` integer
    - `window_days` integer
    - `how_to_lift` string
    - `rate` object: How fast the allowance may be used. A value is null when that limit is not in force.
      - `orders_in_progress` integer
      - `orders_at_once` integer, nullable
      - `minutes_per_window` integer, nullable
      - `window_hours` integer
      - `window_minutes_remaining` number, nullable
  - `next_steps` string[]
  - `mcp_url` string
  - `docs` string

## Other responses

- `422`: Validation failed
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/barevalue/apis/barevalue-api.md) · [All operations](https://skmtc.dev/barevalue/apis/barevalue-api/llms.txt) · [OpenAPI document](https://skmtc.dev/barevalue/apis/barevalue-api/revisions/c47bdd23fcf6?raw)