Skip to content
Bookrail

Collect the key of a confirmed sign up

POST
/v1/signups/{id}/claim

What a waiting terminal polls. Answers pending until the link is opened, then the key, once. No API key.

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required

Identifier of the sign up.

string

Request Body required

Section titled “Request Body required ”
object
poll_token
required

The poll_token returned when the sign up was created.

string
>= 16 characters <= 200 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success.

object
id
required

Identifier of a signup, prefixed with sgn_.

string
/^sgn_[0-9a-f]{32}$/
Example
sgn_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: signup
status
required
string
Allowed values: pending confirmed claimed email_taken expired
email

Echoed back so a client can show where the message went.

string
expires_at

When the confirmation link stops working.

string format: date-time
Example
2026-09-08T07:00:00Z
poll_token

Only for client: "cli", and only in the answer that created the sign up: the token the terminal claims its key with.

string
delivered_to

Present when the key went to a waiting terminal instead of into this response.

string
Allowed values: cli
account
object
id
required

Identifier of a account, prefixed with acct_.

string
/^acct_[0-9a-f]{32}$/
Example
acct_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: account
name
required
string
project
object
id
required

Identifier of a project, prefixed with proj_.

string
/^proj_[0-9a-f]{32}$/
Example
proj_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: project
name
required
string
default_timezone
required
string
default_currency
required
string
api_key

The test key alone. The same object as the test entry of api_keys.

object
id
required

Identifier of a api_key, prefixed with key_.

string
/^key_[0-9a-f]{32}$/
Example
key_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: api_key
environment
required
string
Allowed values: test
kind
required
string
Allowed values: secret
prefix
required
string
api_keys

The keys the sign up created: one test and one live, both secret, with no scopes and no tenant. A sign up confirmed before 24 September 2026 has the test one only.

Array<object>
object
id
required

Identifier of a api_key, prefixed with key_.

string
/^key_[0-9a-f]{32}$/
Example
key_0198f0c2a1b47e2e9a1c0f4d5e6a7b8c
object
required
string
Allowed values: api_key
environment
required
string
Allowed values: test live
kind
required
string
Allowed values: secret
prefix
required
string
secret_key

The test key, in clear text. Shown once: in the confirm of a browser, or in the first successful claim of a terminal. It is stored as a SHA-256 hash and cannot be shown again.

string
Example
sk_test_...
live_secret_key

The live key, in clear text, shown once and at the same moment as secret_key. It books for real and counts against the free plan of the account, which refuses new live bookings at its monthly threshold with 402 plan_limit_reached.

string
Example
sk_live_...

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

400

Section titled “400 ”

Error codes: invalid_body, parameter_invalid, parameter_missing, unsupported_api_version.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

404

Section titled “404 ”

Error codes: resource_missing, signup_not_found.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

410

Section titled “410 ”

Error codes: signup_secret_claimed, signup_secret_expired.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

500

Section titled “500 ”

Error codes: internal_error.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.

503

Section titled “503 ”

Error codes: signup_disabled.

object
error
required
object
type
required
string
Allowed values: invalid_request authentication permission not_found conflict rate_limit policy_violation payment_required internal
code
required

Machine readable code. The set is per operation; each response below lists the ones it can produce.

string
message
required
string
param

The field or header the error is about, when there is one.

string
fix

What to do next, when there is one thing to do. Present on the errors that are about the state of the deployment rather than about the request.

string
doc_url
required
string
request_id
required
string

Headers

Section titled “Headers ”
Bookrail-Request-Id
required
string

Identifier of this request. Quote it to support.

Bookrail-Version
required
string

The API version this response was produced with.