API keys
Create and revoke API keys. The full key is returned only once.
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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Field | Type | Description |
|---|---|---|
namerequired | string | |
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". |
domainIds | array of string | At most 50 items. |
mailboxIds | array of string | Limit the key to these mailboxes: it can only read, search, stream and send mail for them (403 mailbox_scope elsewhere). At most 50 items. |
limits | object | Messages 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.perHour | integer or null | 1 to 100000. |
limits.perDay | integer or null | 1 to 1000000. |
limits.maxStreams | integer or null | 1 to 50. |
recipientAllowlist | array of string | Domains (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. |
expiresAt | string (date-time) or null | When the key stops working (ISO 8601). After it: 401 key_expired. Null or absent: never. |
allowedIps | array of string or null | IPv4 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. |
grants | array 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
name | string | |
expiresAt | string (date-time) or null | When the key stops working (ISO 8601). After it: 401 key_expired. Null or absent: never. |
allowedIps | array of string or null | IPv4 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
gracePeriodSeconds | integer | How 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)