> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Authentication Flow

> Understand the complete flow for setting up and managing admin authentication on self-hosted Databrain instances.

<Info>
  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.
</Info>

<Warning>
  **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.
</Warning>

## Step-by-Step Process

<Steps>
  <Step title="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](/developer-docs/helpers/api-reference/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

    <Note>
      This step is only needed once. If an admin account already exists, proceed to step 2.
    </Note>
  </Step>

  <Step title="2. Create Admin JWT (Sign In)">
    For existing admin accounts, sign in using the [Create Admin JWT](/developer-docs/helpers/api-reference/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.
  </Step>

  <Step title="3. Create Service Token">
    Once you have an admin access token, create a service token using the [Create Service Token](/developer-docs/helpers/api-reference/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

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="4. Rotate Service Token (Optional)">
    Periodically rotate your service token for enhanced security using the [Rotate Service Token](/developer-docs/helpers/api-reference/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

    <Note>
      Use a grace period (e.g., 3600 seconds = 1 hour) to allow time for updating clients before the old token stops working.
    </Note>
  </Step>

  <Step title="5. Reset Admin Password (Optional)">
    Change your admin password using the [Reset Admin Password](/developer-docs/helpers/api-reference/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

    <Warning>
      After resetting your password, you'll need to sign in again using Create Admin JWT to get a new access token.
    </Warning>
  </Step>
</Steps>

## Common Scenarios

<AccordionGroup>
  <Accordion title="First-Time Setup">
    **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.
  </Accordion>

  <Accordion title="Regular Sign-In">
    **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.
  </Accordion>

  <Accordion title="Token Rotation">
    **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).
  </Accordion>

  <Accordion title="Password Reset">
    **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.
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Store Tokens Securely" icon="lock">
    * Never commit tokens to version control
    * Use environment variables or secrets managers
    * Rotate tokens regularly
  </Card>

  <Card title="Use Strong Passwords" icon="shield">
    * Minimum 8 characters
    * Mix of uppercase, lowercase, digits, and special characters
    * No spaces
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    * Rotate service tokens every 6 months
    * Use grace periods during rotation
    * Update all clients before expiration
  </Card>

  <Card title="Monitor Access" icon="eye">
    * Track token usage
    * Revoke compromised tokens immediately
    * Use separate tokens for different environments
  </Card>
</CardGroup>

## Related Documentation

* [Create Admin Account](/developer-docs/helpers/api-reference/create-admin-account) – Create the first admin account
* [Create Admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt) – Sign in and get access token
* [Create Service Token](/developer-docs/helpers/api-reference/create-service-token) – Create organization service token
* [Rotate Service Token](/developer-docs/helpers/api-reference/rotate-service-token) – Rotate service token securely
* [Reset Admin Password](/developer-docs/helpers/api-reference/reset-admin-password) – Change admin password