Docs / API reference

API keys

Create and revoke API keys. The full key is returned only once.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

List API keys

GET /v1/api-keys

Needs a dashboard session or an admin-scoped API key. Expired keys are listed (with expiresAt in the past) until they are revoked.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "data": [{
    "id": string,
    "name": string,
    "prefix": string,
    "scope": "full" | "send" | "read" | "publishable" | "admin",
    "mode": "live" | "test",
    "lastUsedAt": string or null,
    "createdAt": string,
    "domainIds": [string] or null,
    "mailboxIds": [string] or null,
    "limits": {
      "perHour": number or null,
      "perDay": number or null,
      "maxStreams": number or null
    },
    "recipientAllowlist": [string] or null,
    "expiresAt": string or null,
    "expired": boolean,
    "allowedIps": [string] or null,
    "lastUsedIp": string or null,
    "lastUsedUserAgent": string or null,
    "grants": [string] or null,
    "previousSecretExpiresAt": string or null,
    "createdByUserId": string or null,
    "createdByKeyId": string or null
  }]
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Create an API key

POST /v1/api-keys

Needs a dashboard session (or an admin-scoped live key). The full key is returned once. scope defaults to send. test keys never reach a provider (messages are stored as sandboxed). publishable keys (os_pub_…) can only call POST /t/conversion and are safe to put in a web page. full keys send, read and manage content; admin keys (created from a session only) can also change configuration (providers, routing, domains, webhooks, settings) and manage API keys. domainIds limits which sender domains the key may send from. expiresAt and allowedIps contain a leaked key. A key can only create keys no looser than itself (scope, domainIds, mailboxIds, limits, recipientAllowlist, expiresAt, allowedIps, grants): 403 key_wider_than_creator. A key can have at most 100 unrevoked keys it created, expired ones included (ONESEND_MAX_KEYS_PER_KEY; keys created in the dashboard are not limited): 400 too_many_keys. New keys end in a 6-character checksum, so scanners can recognize them offline. The workspace owners get an email.

Authentication: Authorization: Bearer with an API key or a session token.

Request body

application/json, required.

FieldTypeDescription
namerequiredstring
scope"full" | "send" | "read" | "publishable" | "admin"Default send (least privilege). full adds reading and content management; admin adds configuration and API keys. Default "send".
mode"live" | "test"Default "live".
domainIdsarray of stringAt most 50 items.
mailboxIdsarray of stringLimit the key to these mailboxes: it can only read, search, stream and send mail for them (403 mailbox_scope elsewhere). At most 50 items.
limitsobjectMessages per hour and per day (clock hours and UTC days; over the limit: 429 key_rate_limited with retry-after), and open streams (default 5).
limits.perHourinteger or null1 to 100000.
limits.perDayinteger or null1 to 1000000.
limits.maxStreamsinteger or null1 to 50.
recipientAllowlistarray of stringDomains (example.com, with subdomains; *.example.com for subdomains only) and addresses the key may send to. Other recipients: 403 recipient_not_allowed. At most 200 items.
expiresAtstring (date-time) or nullWhen the key stops working (ISO 8601). After it: 401 key_expired. Null or absent: never.
allowedIpsarray of string or nullIPv4 and IPv6 addresses and CIDR ranges the key may be used from (203.0.113.7, 10.0.0.0/8, 2001:db8::/32). Elsewhere: 403 ip_not_allowed. The address is the client address the server sees (ONESEND_TRUST_PROXY decides whether X-Forwarded-For counts). Null or absent: any address. At most 100 items.
grantsarray of "templates:read" | "gallery:submit" | "inbox:agent-changes"Extra permissions on top of the scope: templates:read (list and read templates) and gallery:submit (share templates to the gallery). For example a send key for an app that also lists templates. At most 10 items.

Responses

201 Success

{
  "id": string,
  "name": string,
  "prefix": string,
  "scope": "full" | "send" | "read" | "publishable" | "admin",
  "mode": "live" | "test",
  "lastUsedAt": string or null,
  "createdAt": string,
  "domainIds": [string] or null,
  "mailboxIds": [string] or null,
  "limits": {
    "perHour": number or null,
    "perDay": number or null,
    "maxStreams": number or null
  },
  "recipientAllowlist": [string] or null,
  "expiresAt": string or null,
  "expired": boolean,
  "allowedIps": [string] or null,
  "lastUsedIp": string or null,
  "lastUsedUserAgent": string or null,
  "grants": [string] or null,
  "previousSecretExpiresAt": string or null,
  "createdByUserId": string or null,
  "createdByKeyId": string or null,
  "key": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Update an API key

PATCH /v1/api-keys/{id}

Change the name, the expiry (expiresAt; null: never) or the allowed addresses (allowedIps; null: any). Needs a dashboard session or an admin-scoped API key; a key cannot loosen a key beyond its own settings (403 key_wider_than_creator), and making an expired key live again with a key counts toward the limit of live keys its creator made (400 too_many_keys).

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestring
expiresAtstring (date-time) or nullWhen the key stops working (ISO 8601). After it: 401 key_expired. Null or absent: never.
allowedIpsarray of string or nullIPv4 and IPv6 addresses and CIDR ranges the key may be used from (203.0.113.7, 10.0.0.0/8, 2001:db8::/32). Elsewhere: 403 ip_not_allowed. The address is the client address the server sees (ONESEND_TRUST_PROXY decides whether X-Forwarded-For counts). Null or absent: any address. At most 100 items.

Responses

200 Success

{
  "id": string,
  "name": string,
  "prefix": string,
  "scope": "full" | "send" | "read" | "publishable" | "admin",
  "mode": "live" | "test",
  "lastUsedAt": string or null,
  "createdAt": string,
  "domainIds": [string] or null,
  "mailboxIds": [string] or null,
  "limits": {
    "perHour": number or null,
    "perDay": number or null,
    "maxStreams": number or null
  },
  "recipientAllowlist": [string] or null,
  "expiresAt": string or null,
  "expired": boolean,
  "allowedIps": [string] or null,
  "lastUsedIp": string or null,
  "lastUsedUserAgent": string or null,
  "grants": [string] or null,
  "previousSecretExpiresAt": string or null,
  "createdByUserId": string or null,
  "createdByKeyId": string or null
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Revoke an API key

DELETE /v1/api-keys/{id}

Needs a dashboard session or an admin-scoped API key. Both the current secret and a previous one still in its rotation grace period stop working. The keys it created or rotated are revoked too, and the keys those created or rotated, until none is left; the invitations it sent are canceled and the members who joined through them are removed (and, in turn, the invitations those members sent and the members who joined through them). The workspace owners get an email.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

204 No content

Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Rotate an API key

POST /v1/api-keys/{id}/rotate

Returns a new secret for the same key: same id, name, permissions and restrictions. The old secret keeps working for gracePeriodSeconds (default 24 hours, at most 7 days), so you can deploy the new one, then stops. Rotating again during the grace period ends the earlier secret at once. The new secret is returned once. Needs a dashboard session or an admin-scoped API key. An API key can rotate only itself and the keys in its own creator chain (that it created, or that those created; 403 not_in_key_chain otherwise), and the key that made the rotation is recorded: revoking it, or a leak report about it, revokes the rotated key too, and a leak report of the previous secret of a key last rotated with an API key revokes the whole key. A rotation in the dashboard clears that. The workspace owners get an email.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
gracePeriodSecondsintegerHow long the old secret keeps working, in seconds (default 86,400: 24 hours; at most 604,800: 7 days; 0: it stops at once). Default 86400. 0 to 604800.

Responses

200 Success

{
  "id": string,
  "name": string,
  "prefix": string,
  "scope": "full" | "send" | "read" | "publishable" | "admin",
  "mode": "live" | "test",
  "lastUsedAt": string or null,
  "createdAt": string,
  "domainIds": [string] or null,
  "mailboxIds": [string] or null,
  "limits": {
    "perHour": number or null,
    "perDay": number or null,
    "maxStreams": number or null
  },
  "recipientAllowlist": [string] or null,
  "expiresAt": string or null,
  "expired": boolean,
  "allowedIps": [string] or null,
  "lastUsedIp": string or null,
  "lastUsedUserAgent": string or null,
  "grants": [string] or null,
  "previousSecretExpiresAt": string or null,
  "createdByUserId": string or null,
  "createdByKeyId": string or null,
  "key": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)