Get your own key (no key needed)

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.

post/api/v1/keys

Request

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

Request body

agent_namestring required

What your agent or product is called.

owner_labelstring 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_emailstring email required

A working address: it gets the link that raises the limits and your key page link. Never the key.

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

Example request

{
  "agent_name": "acme-travel-bot",
  "owner_label": "Acme Assistant",
  "notify_url": "https://agent.example/commontape/notices"
}

Response

Issued. The key is in this answer once.

keystring required

Shown once. Send as Authorization: Bearer <key>.

key_idstring uuid required
namestring required

The key's name (your agent_name, with a short suffix when that name was taken).

owner_labelstring required
tier'starter' | 'standard' | 'partner' required
shown_oncetrue required
email_sentboolean 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_urlstring nullable

The push notice address as registered, or null.

notify_secretstring 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_actionsstring[] required

Example response

{
  "key": "ct_live_..."
}

Changes

No recorded changes to this operation across all 1 revision of this API.