---
title: "Get your own key (no key needed)"
method: POST
path: "/api/v1/keys"
---

# Get your own key (no key needed)

`POST /api/v1/keys`

## Request

- Base URL: `https://commontape.com`
- URL: `https://commontape.com/api/v1/keys`
- Auth: none declared

Register once and get a key, shown ONCE in this answer: keep it and send it as Authorization: Bearer <key> on every other call. Starter limits: 30 requests a minute, 3 open holds, 5 bookings a day. The email sent to contact_email carries a link that raises the key to standard limits (60 a minute, 10 open holds, no daily cap) and your key page (usage, the name owners see, rotate, revoke). Limits on registering: 3 keys a day per contact address, 5 per sending IP. Browsers may post the same fields as a form from /docs. The same operation is the register tool over MCP.

## Request body

- object
  - `agent_name` string, required: What your agent or product is called.
  - `owner_label` string, required: The plain name business owners see next to a job from this key: letters, digits, spaces and a few marks; no machine words.
  - `contact_email` string, email, required: A working address: it gets the link that raises the limits and your key page link. Never the key.
  - `notify_url` string, uri: Optional. An https address of yours that takes a POST. CommonTape sends a push notice there (see webhooks) when one of this key's jobs is declined, called off by the owner, booked on the owner's yes, or runs out unanswered. A public host name only (no IP address, no private host); a refusal says why. Without it, poll status.

## Response `201`

Issued. The key is in this answer once.

- object
  - `key` string, required: Shown once. Send as Authorization: Bearer <key>.
  - `key_id` string, uuid, required
  - `name` string, required: The key's name (your agent_name, with a short suffix when that name was taken).
  - `owner_label` string, required
  - `tier` 'starter' | 'standard' | 'partner', required
  - `limits` KeyLimits, required
    - `requests_per_minute` integer, required
    - `open_holds` integer, required
    - `bookings_per_day` integer, nullable, required: null = no daily cap.
  - `standard_limits` KeyLimits, required
    - `requests_per_minute` integer, required
    - `open_holds` integer, required
    - `bookings_per_day` integer, nullable, required: null = no daily cap.
  - `shown_once` true, required
  - `email_sent` boolean, required: Whether the email with the limits link went out. If false, ask for a fresh link later: POST /api/v1/keys/link {contact_email}.
  - `notify_url` string, nullable: The push notice address as registered, or null.
  - `notify_secret` string, nullable: Shown once, only with a notify_url: the secret every push notice is signed with (x-commontape-signature = hex HMAC-SHA256 of the exact body). Keep it with the key. Rotating the key makes a new one, shown once on the key page.
  - `next_actions` string[], required

## Other responses

- `400`: A field is missing or malformed (INVALID_REQUEST). The message names the field; next_actions says fix_request.
- `429`: Too many keys from this address (3 a day) or this connection (5 a day) (RATE_LIMITED). The message says when to try again.
- `default`: Error

---

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