Create an API key

POST

/api-keys

const url = 'https://api.sealpost.app/v1/api-keys';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","mode":"live","scopes":["envelopes:read"],"expires_at":"2026-04-15T12:00:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.sealpost.app/v1/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "mode": "live", "scopes": [ "envelopes:read" ], "expires_at": "2026-04-15T12:00:00Z" }'

Scope api_keys:write. The secret is in the response once and never again. A test key may only create test keys (live_key_required). Honours Idempotency-Key.

Authorizations

ApiKey

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters

Client-chosen key, 1 to 255 characters, scoped to (tenant, API key, method, path). The first response is stored for 24 hours and replayed for repeats with the same body (Idempotent-Replayed: true). A repeat with a different body is a 422 idempotency_key_reused; a repeat while the first request is still running is a 409 idempotency_in_flight (a request that dies mid-flight releases its lock after 60 seconds).

Request Body^required

application/json

object

name

required

string

>= 1 characters <= 100 characters

mode

required

string

Allowed values: live test

scopes

Defaults to every scope the calling key has.

Array<string>

unique items

Allowed values: envelopes:read envelopes:write templates:read templates:write webhooks:write tenant:read tenant:write api_keys:read api_keys:write requests:read

expires_at

Optional hard expiry, must be in the future.

string | null format: date-time

Responses

201

The new key with its secret.

application/json

object

required

string format: uuid

name

required

string

prefix

required

The visible start of the secret, e.g. sk_test_3f9aQ2Lm, enough to tell keys apart.

string

mode

required

string

Allowed values: live test

scopes

required

Array<string>

Allowed values: envelopes:read envelopes:write templates:read templates:write webhooks:write tenant:read tenant:write api_keys:read api_keys:write requests:read

rotated_from_id

The key this one replaced, when minted by a rotation.

string | null format: uuid

created_at

required

string format: date-time

last_used_at

required

Updated at most once a minute.

string | null format: date-time

expires_at

required

string | null format: date-time

revoked_at

required

string | null format: date-time

secret

The full key. Present on the first response only: shown once, never stored, so an idempotent replay of the same request (Idempotent-Replayed: true) omits it.

string

Example

{
  "mode": "live",
  "scopes": [
    "envelopes:read"
  ],
  "secret": "sk_test_EXAMPLE"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

Idempotent-Replayed

boolean

Present and true when the response was replayed from a stored earlier response for the same Idempotency-Key.

400

The request could not be read (malformed JSON, bad header).

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

401

No key, an unknown key, or a revoked or expired key.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

403

The key is valid but lacks the scope, or a test key tried a live-only action.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

409

A request with the same Idempotency-Key is still in flight.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

422

The request was read but a value is invalid, or an Idempotency-Key was reused with a different body.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

429

The key is over its per-minute budget (600 live, 60 test, sliding window).

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

Retry-After

integer

Seconds to wait before retrying.

RateLimit-Limit

integer

Requests allowed per minute for this key (600 live, 60 test).

RateLimit-Remaining

integer

Requests remaining in the current window.

RateLimit-Reset

integer

Seconds until the window has capacity again.

500

Something failed on our side. The request_id is in our logs.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

Create an API key

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

Headers

400

Example

Headers

401

Example

Headers

403

Example

Headers

409

Example

Headers

422

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required