Skip to main content
This guide walks you through the complete authentication flow for self-hosted Databrain instances. Follow these steps in order to set up your admin account and service tokens.
Self-Hosted Only: All endpoints described in this flow are available only on self-hosted Databrain instances. They will return errors on cloud (SaaS) deployments.

​
Step-by-Step Process

1

1. Create Admin Account (First Time Only)

If this is your first time setting up your self-hosted instance, create the initial admin account using the Create Admin Account endpoint.What you need:
  • Admin first name
  • Admin email address
  • Secure password (meets complexity requirements)
  • Company name
What you get:
  • An accessToken (JWT) that you can use for subsequent admin operations
This step is only needed once. If an admin account already exists, proceed to step 2.
2

2. Create Admin JWT (Sign In)

For existing admin accounts, sign in using the Create Admin JWT endpoint to receive an access token.What you need:
  • Admin email address
  • Admin password
What you get:
  • An accessToken (JWT) for authenticated admin operations
Use this token in the Authorization: Bearer <accessToken> header for admin-only endpoints.
3

3. Create Service Token

Once you have an admin access token, create a service token using the Create Service Token endpoint.What you need:
  • Admin accessToken from step 1 or 2 (in Authorization header)
  • A UUID value for the service token
What you get:
  • A serviceToken (UUID) that can be used for organization-level operations such as:
    • Creating Data App API tokens
    • Managing Data Apps
    • Export/import operations
Generate a UUID using your preferred method (e.g., uuidv4() in Node.js, uuid.uuid4() in Python). Store this token securely as it provides elevated permissions.
4

4. Rotate Service Token (Optional)

Periodically rotate your service token for enhanced security using the Rotate Service Token endpoint.What you need:
  • Admin accessToken (in Authorization header)
  • Current service token UUID
  • Expiration grace period (in seconds)
What you get:
  • A new serviceToken UUID
  • The old token expires after the grace period
Use a grace period (e.g., 3600 seconds = 1 hour) to allow time for updating clients before the old token stops working.
5

5. Reset Admin Password (Optional)

Change your admin password using the Reset Admin Password endpoint.What you need:
  • Admin accessToken (in Authorization header)
  • Current password
  • New password (meets complexity requirements)
What you get:
  • Confirmation that the password was changed successfully
After resetting your password, you’ll need to sign in again using Create Admin JWT to get a new access token.

​
Common Scenarios

Complete flow for new installations:
  1. Create Admin Account → Get accessToken
  2. Create Service Token → Get serviceToken
  3. Use serviceToken for organization operations
This is a one-time setup process.
For existing admin accounts:
  1. Create Admin JWT → Get accessToken
  2. Use accessToken for admin operations
  3. Create or rotate service tokens as needed
Repeat this whenever you need to perform admin operations.
For security best practices:
  1. Create Admin JWT → Get accessToken
  2. Rotate Service Token → Get new serviceToken
  3. Update all clients with new serviceToken
  4. Old token expires after grace period
Rotate tokens periodically (recommended: every 6 months).
When you need to change your password:
  1. Create Admin JWT → Get accessToken
  2. Reset Admin Password → Confirm change
  3. Create Admin JWT again → Get new accessToken
After password reset, your old access tokens may become invalid.

​
Security Best Practices

Store Tokens Securely

  • Never commit tokens to version control
  • Use environment variables or secrets managers
  • Rotate tokens regularly

Use Strong Passwords

  • Minimum 8 characters
  • Mix of uppercase, lowercase, digits, and special characters
  • No spaces

Rotate Regularly

  • Rotate service tokens every 6 months
  • Use grace periods during rotation
  • Update all clients before expiration

Monitor Access

  • Track token usage
  • Revoke compromised tokens immediately
  • Use separate tokens for different environments