Create Service Token (Self-Hosted)

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"
}

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"
}

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

api

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 Code	Description
`200`	OK – Service token created or updated; response contains `key`
`400`	Bad Request – Invalid or missing `token` (must be a valid UUID)
`500`	Internal Server Error – Server error or self-hosted-only error

Possible Errors

Code	Message	HTTP Status
`INVALID_REQUEST_BODY`	Joi validation message (e.g. `"token" is required`, `"token" must be a valid GUID`)	400
`SELFHOSTED_APP_ERROR`	This feature is only available for self-hosted instances	500
`ACCOUNT_NOT_FOUND`	ACCOUNT_NOT_FOUND	500
`INTERNAL_SERVER_ERROR`	INTERNAL_SERVER_ERROR	500

Rotate Service Token – Rotate the service token with an expiration window
Create Admin Account – Create the first admin account (self-hosted)
Create Admin JWT – Get an access token for admin APIs

Create Admin JWT (Self-Hosted)

Rotate Service Token

Documentation Index

​Authentication

​Headers

​Request Body

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

​Related

Authentication

Headers

Request Body

Response

Examples

HTTP Status Code Summary

Possible Errors

Related