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"
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/api-tokens', {
method: 'POST',
headers: {
'Authorization': 'Bearer service_token_xyz...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
})
});
const data = await response.json();
console.log('New API Key:', data.key);
// Store this key securely!
import requests
url = "https://api.usedatabrain.com/api/v2/data-app/api-tokens"
headers = {
"Authorization": "Bearer service_token_xyz...",
"Content-Type": "application/json"
}
payload = {
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(f"New API Key: {data['key']}")
# Store this key securely!
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class CreateApiToken {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
String requestBody = """
{
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/api-tokens"))
.header("Authorization", "Bearer service_token_xyz...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
// Store the key securely!
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type CreateApiTokenRequest struct {
DataAppName string `json:"dataAppName"`
Name string `json:"name"`
}
type CreateApiTokenResponse struct {
Key string `json:"key"`
Error interface{} `json:"error"`
}
func main() {
requestBody := CreateApiTokenRequest{
DataAppName: "Customer Portal Analytics",
Name: "Production API Key",
}
jsonData, _ := json.Marshal(requestBody)
req, _ := http.NewRequest("POST", "https://api.usedatabrain.com/api/v2/data-app/api-tokens", bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer service_token_xyz...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result CreateApiTokenResponse
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("New API Key: %s\n", result.Key)
// Store this key securely!
}
<?php
$curl = curl_init();
$data = [
'dataAppName' => 'Customer Portal Analytics',
'name' => 'Production API Key'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.usedatabrain.com/api/v2/data-app/api-tokens',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer service_token_xyz...',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
echo 'New API Key: ' . $result['key'];
// Store this key securely!
?>
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/api-tokens')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer service_token_xyz...'
request['Content-Type'] = 'application/json'
request.body = {
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
}.to_json
response = http.request(request)
result = JSON.parse(response.body)
puts "New API Key: #{result['key']}"
# Store this key securely!
{
"key": "550e8400-e29b-41d4-a716-446655440000"
}
{
"error": {
"code": "INVALID_REQUEST_BODY",
"message": "\"dataAppName\" is required"
}
}
{
"error": {
"code": "DATA_APP_NOT_FOUND",
"message": "Data app not found"
}
}
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Invalid Service Token"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "INTERNAL_SERVER_ERROR"
}
}
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"
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/api-tokens', {
method: 'POST',
headers: {
'Authorization': 'Bearer service_token_xyz...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
})
});
const data = await response.json();
console.log('New API Key:', data.key);
// Store this key securely!
import requests
url = "https://api.usedatabrain.com/api/v2/data-app/api-tokens"
headers = {
"Authorization": "Bearer service_token_xyz...",
"Content-Type": "application/json"
}
payload = {
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(f"New API Key: {data['key']}")
# Store this key securely!
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class CreateApiToken {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
String requestBody = """
{
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/api-tokens"))
.header("Authorization", "Bearer service_token_xyz...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
// Store the key securely!
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type CreateApiTokenRequest struct {
DataAppName string `json:"dataAppName"`
Name string `json:"name"`
}
type CreateApiTokenResponse struct {
Key string `json:"key"`
Error interface{} `json:"error"`
}
func main() {
requestBody := CreateApiTokenRequest{
DataAppName: "Customer Portal Analytics",
Name: "Production API Key",
}
jsonData, _ := json.Marshal(requestBody)
req, _ := http.NewRequest("POST", "https://api.usedatabrain.com/api/v2/data-app/api-tokens", bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer service_token_xyz...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result CreateApiTokenResponse
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("New API Key: %s\n", result.Key)
// Store this key securely!
}
<?php
$curl = curl_init();
$data = [
'dataAppName' => 'Customer Portal Analytics',
'name' => 'Production API Key'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.usedatabrain.com/api/v2/data-app/api-tokens',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer service_token_xyz...',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
echo 'New API Key: ' . $result['key'];
// Store this key securely!
?>
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/api-tokens')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer service_token_xyz...'
request['Content-Type'] = 'application/json'
request.body = {
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
}.to_json
response = http.request(request)
result = JSON.parse(response.body)
puts "New API Key: #{result['key']}"
# Store this key securely!
{
"key": "550e8400-e29b-41d4-a716-446655440000"
}
{
"error": {
"code": "INVALID_REQUEST_BODY",
"message": "\"dataAppName\" is required"
}
}
{
"error": {
"code": "DATA_APP_NOT_FOUND",
"message": "Data app not found"
}
}
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Invalid Service Token"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "INTERNAL_SERVER_ERROR"
}
}
API Tokens
Create API Token for Data App
Generate a new API token for a specific Data App to enable embed operations.
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"
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/api-tokens', {
method: 'POST',
headers: {
'Authorization': 'Bearer service_token_xyz...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
})
});
const data = await response.json();
console.log('New API Key:', data.key);
// Store this key securely!
import requests
url = "https://api.usedatabrain.com/api/v2/data-app/api-tokens"
headers = {
"Authorization": "Bearer service_token_xyz...",
"Content-Type": "application/json"
}
payload = {
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(f"New API Key: {data['key']}")
# Store this key securely!
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class CreateApiToken {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
String requestBody = """
{
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/api-tokens"))
.header("Authorization", "Bearer service_token_xyz...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
// Store the key securely!
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type CreateApiTokenRequest struct {
DataAppName string `json:"dataAppName"`
Name string `json:"name"`
}
type CreateApiTokenResponse struct {
Key string `json:"key"`
Error interface{} `json:"error"`
}
func main() {
requestBody := CreateApiTokenRequest{
DataAppName: "Customer Portal Analytics",
Name: "Production API Key",
}
jsonData, _ := json.Marshal(requestBody)
req, _ := http.NewRequest("POST", "https://api.usedatabrain.com/api/v2/data-app/api-tokens", bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer service_token_xyz...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result CreateApiTokenResponse
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("New API Key: %s\n", result.Key)
// Store this key securely!
}
<?php
$curl = curl_init();
$data = [
'dataAppName' => 'Customer Portal Analytics',
'name' => 'Production API Key'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.usedatabrain.com/api/v2/data-app/api-tokens',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer service_token_xyz...',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
echo 'New API Key: ' . $result['key'];
// Store this key securely!
?>
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/api-tokens')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer service_token_xyz...'
request['Content-Type'] = 'application/json'
request.body = {
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
}.to_json
response = http.request(request)
result = JSON.parse(response.body)
puts "New API Key: #{result['key']}"
# Store this key securely!
{
"key": "550e8400-e29b-41d4-a716-446655440000"
}
{
"error": {
"code": "INVALID_REQUEST_BODY",
"message": "\"dataAppName\" is required"
}
}
{
"error": {
"code": "DATA_APP_NOT_FOUND",
"message": "Data app not found"
}
}
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Invalid Service Token"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "INTERNAL_SERVER_ERROR"
}
}
POST
/
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"
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/api-tokens', {
method: 'POST',
headers: {
'Authorization': 'Bearer service_token_xyz...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
})
});
const data = await response.json();
console.log('New API Key:', data.key);
// Store this key securely!
import requests
url = "https://api.usedatabrain.com/api/v2/data-app/api-tokens"
headers = {
"Authorization": "Bearer service_token_xyz...",
"Content-Type": "application/json"
}
payload = {
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(f"New API Key: {data['key']}")
# Store this key securely!
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class CreateApiToken {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
String requestBody = """
{
"dataAppName": "Customer Portal Analytics",
"name": "Production API Key"
}""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/api-tokens"))
.header("Authorization", "Bearer service_token_xyz...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
// Store the key securely!
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type CreateApiTokenRequest struct {
DataAppName string `json:"dataAppName"`
Name string `json:"name"`
}
type CreateApiTokenResponse struct {
Key string `json:"key"`
Error interface{} `json:"error"`
}
func main() {
requestBody := CreateApiTokenRequest{
DataAppName: "Customer Portal Analytics",
Name: "Production API Key",
}
jsonData, _ := json.Marshal(requestBody)
req, _ := http.NewRequest("POST", "https://api.usedatabrain.com/api/v2/data-app/api-tokens", bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer service_token_xyz...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result CreateApiTokenResponse
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("New API Key: %s\n", result.Key)
// Store this key securely!
}
<?php
$curl = curl_init();
$data = [
'dataAppName' => 'Customer Portal Analytics',
'name' => 'Production API Key'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.usedatabrain.com/api/v2/data-app/api-tokens',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer service_token_xyz...',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
echo 'New API Key: ' . $result['key'];
// Store this key securely!
?>
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/api-tokens')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer service_token_xyz...'
request['Content-Type'] = 'application/json'
request.body = {
dataAppName: 'Customer Portal Analytics',
name: 'Production API Key'
}.to_json
response = http.request(request)
result = JSON.parse(response.body)
puts "New API Key: #{result['key']}"
# Store this key securely!
{
"key": "550e8400-e29b-41d4-a716-446655440000"
}
{
"error": {
"code": "INVALID_REQUEST_BODY",
"message": "\"dataAppName\" is required"
}
}
{
"error": {
"code": "DATA_APP_NOT_FOUND",
"message": "Data app not found"
}
}
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Invalid Service Token"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "INTERNAL_SERVER_ERROR"
}
}
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.
Use this endpoint for all new integrations. This is the recommended endpoint format.This endpoint still works but will be deprecated. Please migrate to the new endpoint format.
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
- New Endpoint (Recommended)
- Legacy Endpoint (Deprecated Soon)
POST https://api.usedatabrain.com/api/v2/data-app/api-tokens
POST https://api.usedatabrain.com/api/v2/dataApp/api-tokens
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:- In Settings page, navigate to the Service Tokens section.
- Click the “Generate Token” button to create a new service token if you don’t have one already.
Headers
string
required
Bearer token for API authentication. Use your service token (not data app API key).
Authorization: Bearer service_token_xyz...
string
required
Must be set to
application/json for all requests.Content-Type: application/json
Request Body
string
required
The name of the Data App to create the API token for. This must exactly match an existing Data App name.
Show Finding Data App names
Show Finding Data App names
- Use the List Data Apps API to get all Data App names
- Check your Databrain dashboard for Data App configurations
- The name is case-sensitive
string
required
A descriptive name/label for the API token. This helps identify the token’s purpose.
Show Naming recommendations
Show Naming recommendations
- Use descriptive names like “Production Token”, “Development Token”, “Partner API Key”
- Include environment or purpose information
- Keep names unique within each Data App for easy identification
Response
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.
object
Examples
HTTP Status Code Summary
| Status Code | Description |
|---|---|
200 | OK - API token created successfully |
400 | Bad Request - Invalid request parameters |
500 | Internal Server Error - Server error occurred |
Possible Errors
| Error Code | HTTP Status | Description |
|---|---|---|
INVALID_REQUEST_BODY | 400 | Missing or invalid dataAppName or name |
DATA_APP_NOT_FOUND | 400 | Data App with given name not found |
AUTHENTICATION_ERROR | 400 | Invalid or missing service token |
INTERNAL_SERVER_ERROR | 500 | Server 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
In Settings page, navigate to the Service Tokens section. Click the “Generate Token” button to create a new service token if you don’t have one already.
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
⌘I

