Skip to main content
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/api-tokens \
  --header 'Authorization: Bearer service_token_xyz...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dataAppName": "Customer Portal Analytics",
    "name": "Production API Key"
  }'

{
  "key": "550e8400-e29b-41d4-a716-446655440000"
}
POST
https://api.usedatabrain.com
/
api
/
v2
/
data-app
/
api-tokens
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/api-tokens \
  --header 'Authorization: Bearer service_token_xyz...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dataAppName": "Customer Portal Analytics",
    "name": "Production API Key"
  }'

{
  "key": "550e8400-e29b-41d4-a716-446655440000"
}
Create a new API token for a Data App. API tokens are used to authenticate requests for embed operations such as creating embeds, generating guest tokens, and querying metrics.
Each Data App can have multiple API tokens. This is useful for:
  • Separating tokens by environment (development, staging, production)
  • Rotating tokens without service interruption
  • Tracking API usage by token
Authentication Requirement: This endpoint requires a service token (not a data app API key). Service tokens have elevated permissions to manage API tokens across your organization.

​
Endpoint Formats

​
Authentication

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions. To access your service token:
  1. Go to your Databrain dashboard and open Settings.
  2. Navigate to Settings.
  3. Find the Service Tokens section.
  4. Click the “Generate Token” button to generate a new service token if you don’t have one already.
Use this token as the Bearer value in your Authorization header.

​
Headers

​
Authorization
string
required
Bearer token for API authentication. Use your service token (not data app API key).
Authorization: Bearer service_token_xyz...
​
Content-Type
string
required
Must be set to application/json for all requests.
Content-Type: application/json

​
Request Body

​
dataAppName
string
required
The name of the Data App to create the API token for. This must exactly match an existing Data App name.
​
name
string
required
A descriptive name/label for the API token. This helps identify the token’s purpose.

​
Response

​
key
string
The newly generated API token (UUID format). Store this securely as it will be used for all embed operations.
Important: The API key is only shown once. Store it securely immediately after creation.
​
error
object
Error object returned only when the request fails. Not included in successful responses.

​
Examples

​
HTTP Status Code Summary

Status CodeDescription
200OK - API token created successfully
400Bad Request - Invalid request parameters
500Internal Server Error - Server error occurred

​
Possible Errors

Error CodeHTTP StatusDescription
INVALID_REQUEST_BODY400Missing or invalid dataAppName or name
DATA_APP_NOT_FOUND400Data App with given name not found
AUTHENTICATION_ERROR400Invalid or missing service token
INTERNAL_SERVER_ERROR500Server error

​
API Token Scope

When an API token is created, it is automatically assigned the following scope:
  • Access Metrics - Query and retrieve metric data
  • Access Dashboards - Access and embed dashboards

​
Quick Start Guide

1

Get your service token

Go to your Databrain dashboard, navigate to Settings > Service Tokens, and generate a new service token if you don’t have one.
2

Verify the Data App exists

Use the List Data Apps API to confirm the Data App exists:
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app' \
  --header 'Authorization: Bearer service_token_xyz...'
3

Create the API token

Create a new API token for your Data App:
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/api-tokens \
  --header 'Authorization: Bearer service_token_xyz...' \
  --header 'Content-Type: application/json' \
  --data '{"dataAppName": "My Data App", "name": "Production Token"}'
4

Store the API key securely

The response contains the API key. Store it securely as it won’t be shown again:
// Store in environment variables
process.env.DATABRAIN_API_KEY = response.key;

// Or in a secrets manager
await secretsManager.setSecret('databrain-api-key', response.key);
5

Use the API key for embed operations

Use the new API key to create embeds and generate guest tokens:
curl --request POST \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds' \
  --header 'Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data '{...}'

​
Best Practices

Store Keys Securely

Never commit API keys to version control. Use environment variables or secrets managers.

Use Descriptive Names

Name tokens clearly (e.g., “Production API Key”, “Dev Environment Token”)

Rotate Regularly

Rotate API keys periodically for enhanced security using the Rotate API Key endpoint.

Separate by Environment

Create separate tokens for development, staging, and production environments.

​
Next Steps

List API Tokens

View all API tokens for a Data App

Rotate API Key

Rotate API keys for enhanced security

Create Embed

Use your API token to create embed configurations

Generate Guest Token

Generate guest tokens for your end users