Authentication
Datasource APIs
Semantic Layer APIs
Embeds
Data App APIs
Metric APIs
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"
}
Self-Hosted APIs
Create Service Token (Self-Hosted)
Create or save a service token for your self-hosted Databrain instance. Available only on self-hosted deployments.
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
/
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.
On error, the API returns a JSON object with
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 theAuthorization header. Obtain one by calling Create Admin JWT first.
Headers
Bearer token for an authenticated admin user.
Authorization: Bearer <access_token>
Must be
application/json when sending a JSON body.Content-Type: application/json
Request Body
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: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).
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 |
Related
- 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
⌘I