Account & keys

Plan, limits, usage and secret-key management.

GET /v1/account
GET /v1/keys
POST /v1/keys
DELETE /v1/keys/{key_id}

Plan, limits and usage

GET /v1/account

Credential: Secret key (Authorization: Bearer spk_live_…)

Responses

200 Account.

200 response of GET /v1/account
Field	Type	Description
`account_id` required	string	Pattern `^acct_[0-9A-HJKMNP-TV-Z]{26}$`.
`email` required	string	Format email.
`plan` required	string	One of `free`, `pro`.
`limits` required	object
`limits.participants_per_session` required	integer
`limits.sessions_per_month` required	integer
`limits.presentations` required	integer
`limits.concurrent_live_sessions` required	integer
`usage` required	object
`usage.sessions_this_month` required	integer	At least 0.
`usage.presentations` required	integer	At least 0.
`usage.live_sessions` required	integer	At least 0.
`usage.period_start` required	string	Format date-time. Example `2026-10-11T18:04:05Z`.
`usage.resets_at` required	string	Format date-time. Example `2026-10-11T18:04:05Z`.
`billing` required	object
`billing.status` required	string \| null	Stripe subscription status (e.g. `active`, `trialing`, `past_due`, `canceled`), or null with no subscription.
`billing.current_period_end` required	string \| null	Format date-time.
`billing.cancel_at_period_end` required	boolean
`warnings` required	array of object
`warnings[].code` required	string	Presentation saves and `POST /v1/validate`: `defaulted`, `long_prompt`, `few_options`, `speed_bonus_unused`, `ids_removed`, `live_session_uses_previous_version`. `GET /v1/account`: `payment_past_due` (Pro stays active while Stripe retries) and `secret_key_in_browser` (a key was sent from a browser and refused). Clients must accept codes not listed here. One of `defaulted`, `long_prompt`, `few_options`, `speed_bonus_unused`, `ids_removed`, `live_session_uses_previous_version`, `payment_past_due`, `secret_key_in_browser`.
`warnings[].path`	string
`warnings[].message` required	string

Status	Error codes
401	`missing_credentials`, `invalid_credentials`, `not_signed_in` (`/v1/web/*`).
403	`wrong_credential_type`, `secret_key_in_browser`, `csrf_failed`, `recent_auth_required`, `session_full`, `nickname_rejected`.
429	`rate_limited`, with `retry_after_s`.
500	`internal_error`.

List secret keys

GET /v1/keys

Credential: Secret key (Authorization: Bearer spk_live_…)

Responses

200 Active keys.

200 response of GET /v1/keys
Field	Type	Description
`data` required	array of object
`data[].key_id` required	string	Pattern `^key_[0-9A-HJKMNP-TV-Z]{26}$`.
`data[].name` required	string
`data[].last4` required	string	exactly 4 chars.
`data[].created_at` required	string	Format date-time. Example `2026-10-11T18:04:05Z`.
`data[].last_used_at` required	string \| null	Format date-time.

Status	Error codes
401	`missing_credentials`, `invalid_credentials`, `not_signed_in` (`/v1/web/*`).
403	`wrong_credential_type`, `secret_key_in_browser`, `csrf_failed`, `recent_auth_required`, `session_full`, `nickname_rejected`.
429	`rate_limited`, with `retry_after_s`.
500	`internal_error`.

Create a secret key

POST /v1/keys

Credential: Secret key (Authorization: Bearer spk_live_…)

The secret is returned once. At most 10 active keys (402 quota_exceeded, limit: keys).

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string	The first response is stored 24 h per (account, key) and replayed verbatim. Same key with a different body → `409 idempotency_conflict`. 1–64 chars.

Request body

application/json

Request body of POST /v1/keys
Field	Type	Description
`name` required	string	1–40 chars.

Responses

201 Created.

201 response of POST /v1/keys
Field	Type	Description
`key_id` required	string	Pattern `^key_[0-9A-HJKMNP-TV-Z]{26}$`.
`name` required	string
`secret_key` required	string	Pattern `^spk_live_[0-9A-Za-z]{32,}$`.
`created_at` required	string	Format date-time. Example `2026-10-11T18:04:05Z`.

Status	Error codes
400	`invalid_json`, `validation_failed` (see `details`), `invalid_request`.
401	`missing_credentials`, `invalid_credentials`, `not_signed_in` (`/v1/web/*`).
402	`quota_exceeded` with `limit`, `used`, `max`, `resets_at`, `upgrade_url`.
403	`wrong_credential_type`, `secret_key_in_browser`, `csrf_failed`, `recent_auth_required`, `session_full`, `nickname_rejected`.
409	`session_ended`, `idempotency_conflict` (same key, different body; or, retryable, the first request with that key is still in progress — retry the same request in a few seconds).
429	`rate_limited`, with `retry_after_s`.
500	`internal_error`.

Revoke a secret key

DELETE /v1/keys/{key_id}

Credential: Secret key (Authorization: Bearer spk_live_…)

Takes effect within 60 seconds. A key may revoke itself, including the last one.

Parameters

Name	In	Type	Description
`key_id` required	path	string	Pattern `^key_[0-9A-HJKMNP-TV-Z]{26}$`.

Responses

200 Revoked.

200 response of DELETE /v1/keys/{key_id}
Field	Type	Description
`revoked` required	`true`
`key_id` required	string	Pattern `^key_[0-9A-HJKMNP-TV-Z]{26}$`.

Status	Error codes
401	`missing_credentials`, `invalid_credentials`, `not_signed_in` (`/v1/web/*`).
403	`wrong_credential_type`, `secret_key_in_browser`, `csrf_failed`, `recent_auth_required`, `session_full`, `nickname_rejected`.
404	`presentation_not_found`, `session_not_found`, `pin_not_found`, `question_not_found`, `key_not_found`, `grant_not_found`, `oauth_request_not_found`, `route_not_found`. Ownership failures are always 404.
429	`rate_limited`, with `retry_after_s`.
500	`internal_error`.