Skip to main content
POST
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. In Settings page, navigate to the Service Tokens section.
  2. Click the “Generate Token” button to create a new service token if you don’t have one already.
Use this token as the Bearer value in your Authorization header.

Headers

string
required
Bearer token for API authentication. Use your service token (not data app API key).
string
required
Must be set to application/json for all requests.

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.
string
required
A descriptive name/label for the API token. This helps identify the token’s purpose.

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
Error object returned only when the request fails. Not included in successful responses.

Examples

HTTP Status Code Summary

Possible Errors

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:
3

Create the API token

Create a new API token for your Data App:
4

Store the API key securely

The response contains the API key. Store it securely as it won’t be shown again:
5

Use the API key for embed operations

Use the new API key to create embeds and generate guest tokens:

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