Docs / API reference

License

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

License status of this server

GET /v1/license

email (who bought the key) is shown only to whoever may change the license (canManage): the instance admins (ONESEND_ADMIN_EMAILS), or, when none are configured, the owner of the server's first workspace.

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

Responses

200 Success

{
  "required": boolean,
  "status": "none" | "active" | "expired" | "revoked" | "invalid",
  "email": string or null,
  "last4": string or null,
  "validUntil": string or null,
  "checkedAt": string or null,
  "message": string or null,
  "buyUrl": string,
  "canManage": boolean
}
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)

Activate a license key on this server

POST /v1/license

Activates the key with the license server for this installation (one key, one installation). Errors from the license server: invalid_license, wrong_product (a Mac app key), seat_limit (the key is active on another installation: remove it there, or free that seat with POST /v1/license/free-other; details.activations lists the installations with their ids), revoked.

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

Request body

application/json, required.

FieldTypeDescription
keyrequiredstring

Responses

200 Success

{
  "required": boolean,
  "status": "none" | "active" | "expired" | "revoked" | "invalid",
  "email": string or null,
  "last4": string or null,
  "validUntil": string or null,
  "checkedAt": string or null,
  "message": string or null,
  "buyUrl": string,
  "canManage": boolean
}
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)

Free the license key for another installation

DELETE /v1/license

Frees the key at the license server and forgets it here (ONESEND_LICENSE_KEY is not activated again on its own). 409 license_server_unreachable while the license server cannot be reached: the key is kept, because its seat would stay taken. With force=true the key is removed anyway; its seat stays taken until it is freed with POST /v1/license/free-other from the next installation.

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

Parameters

NameInTypeDescription
forcequery"true" | "false"

Responses

200 Success

{
  "required": boolean,
  "status": "none" | "active" | "expired" | "revoked" | "invalid",
  "email": string or null,
  "last4": string or null,
  "validUntil": string or null,
  "checkedAt": string or null,
  "message": string or null,
  "buyUrl": string,
  "canManage": boolean
}
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)

Check the license with the license server now

POST /v1/license/refresh

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

Responses

200 Success

{
  "required": boolean,
  "status": "none" | "active" | "expired" | "revoked" | "invalid",
  "email": string or null,
  "last4": string or null,
  "validUntil": string or null,
  "checkedAt": string or null,
  "message": string or null,
  "buyUrl": string,
  "canManage": boolean
}
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)

Free a seat taken by another installation

POST /v1/license/free-other

For an installation that was lost (or whose key was removed while offline): deactivates that activation of the key at the license server, so this server can activate the key. The activation ids are in the seat_limit error of POST /v1/license (details.activations). Whoever may change the license, signed in.

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

Request body

application/json, required.

FieldTypeDescription
keyrequiredstring
activationIdrequiredstring

Responses

200 Success

{
  "ok": true
}
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)