Skip to main content
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/service-token \
  --header 'Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"token":"550e8400-e29b-41d4-a716-446655440000"}'

{
  "key": "550e8400-e29b-41d4-a716-446655440000"
}
POST
https://api.usedatabrain.com
/
api
/
v2
/
service-token
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/service-token \
  --header 'Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"token":"550e8400-e29b-41d4-a716-446655440000"}'

{
  "key": "550e8400-e29b-41d4-a716-446655440000"
}
Create or register a service token for your self-hosted instance. If no service token exists, a new one is created; if one already exists, it is updated with the provided token value. Service tokens are used for organization-level operations such as managing Data Apps and API tokens.
Self-Hosted Only: This endpoint is available only on self-hosted Databrain instances. It returns an error on cloud (SaaS) deployments.
Authentication Requirement: This endpoint requires an authenticated admin user (Bearer token from Create Admin JWT) and a subscribed account.

​
Authentication

Use a valid admin session token in the Authorization header. Obtain one by calling Create Admin JWT first.

​
Headers

​
Authorization
string
required
Bearer token for an authenticated admin user.
Authorization: Bearer <access_token>
​
Content-Type
string
required
Must be application/json when sending a JSON body.
Content-Type: application/json

​
Request Body

​
token
string
required
The service token value. Must be a valid UUID (e.g. RFC 4122). The backend stores this as the service token ID for your company. Generate a UUID (e.g. via uuidv4) and send it here.

​
Response

On success, the API returns 200 with a JSON object:
​
key
string
The service token (UUID). Use this value as the Bearer token for service-level API calls (e.g. creating Data App API tokens, export/import dashboard).
On error, the API returns a JSON object with error.code and error.message and an appropriate HTTP status (400 or 500).

​
Examples

​
HTTP Status Code Summary

Status CodeDescription
200OK – Service token created or updated; response contains key
400Bad Request – Invalid or missing token (must be a valid UUID)
500Internal Server Error – Server error or self-hosted-only error

​
Possible Errors

CodeMessageHTTP Status
INVALID_REQUEST_BODYJoi validation message (e.g. "token" is required, "token" must be a valid GUID)400
SELFHOSTED_APP_ERRORThis feature is only available for self-hosted instances500
ACCOUNT_NOT_FOUNDACCOUNT_NOT_FOUND500
INTERNAL_SERVER_ERRORINTERNAL_SERVER_ERROR500