> ## 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.

# Create Service Token (Self-Hosted)

> Create or save a service token for your self-hosted Databrain instance. Available only on self-hosted deployments.

Create or register a service token for your self-hosted instance. If no service token exists, a new one is created; if one already exists, it is updated with the provided token value. Service tokens are used for organization-level operations such as managing Data Apps and API tokens.

<Warning>
  **Self-Hosted Only:** This endpoint is available only on **self-hosted** Databrain instances. It returns an error on cloud (SaaS) deployments.
</Warning>

<Warning>
  **Authentication Requirement:** This endpoint requires an authenticated admin user (Bearer token from [Create Admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt)) and a subscribed account.
</Warning>

## Authentication

Use a valid admin session token in the `Authorization` header. Obtain one by calling [Create Admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt) first.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for an authenticated admin user.

  ```
  Authorization: Bearer <access_token>
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json` when sending a JSON body.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="token" type="string" required>
  The service token value. Must be a valid **UUID** (e.g. RFC 4122). The backend stores this as the service token ID for your company. Generate a UUID (e.g. via `uuidv4`) and send it here.
</ParamField>

## Response

On success, the API returns **200** with a JSON object:

<ResponseField name="key" type="string">
  The service token (UUID). Use this value as the Bearer token for service-level API calls (e.g. creating Data App API tokens, export/import dashboard).
</ResponseField>

On error, the API returns a JSON object with `error.code` and `error.message` and an appropriate HTTP status (400 or 500).

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/service-token \
      --header 'Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{"token":"550e8400-e29b-41d4-a716-446655440000"}'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/service-token', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ADMIN_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        token: '550e8400-e29b-41d4-a716-446655440000'
      })
    });
    const data = await response.json();
    if (data.error) throw new Error(data.error.message);
    console.log('Service token:', data.key);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/service-token"
    headers = {
        "Authorization": "Bearer YOUR_ADMIN_ACCESS_TOKEN",
        "Content-Type": "application/json"
    }
    payload = {"token": "550e8400-e29b-41d4-a716-446655440000"}

    response = requests.post(url, headers=headers, json=payload)
    data = response.json()
    if data.get("error"):
        raise Exception(data["error"].get("message", "Request failed"))
    print("Service token:", data["key"])
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success (200) theme={"dark"}
    {
      "key": "550e8400-e29b-41d4-a716-446655440000"
    }
    ```

    ```json Error (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"token\" is required"
      }
    }
    ```

    ```json Error (400) - Invalid UUID theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"token\" must be a valid GUID"
      }
    }
    ```

    ```json Error (500) theme={"dark"}
    {
      "error": {
        "code": "SELFHOSTED_APP_ERROR",
        "message": "This feature is only available for self-hosted instances"
      }
    }
    ```
  </ResponseExample>
</Panel>

## HTTP Status Code Summary

| Status Code | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `200`       | **OK** – Service token created or updated; response contains `key`  |
| `400`       | **Bad Request** – Invalid or missing `token` (must be a valid UUID) |
| `500`       | **Internal Server Error** – Server error or self-hosted-only error  |

## Possible Errors

| Code                    | Message                                                                             | HTTP Status |
| ----------------------- | ----------------------------------------------------------------------------------- | ----------- |
| `INVALID_REQUEST_BODY`  | Joi validation message (e.g. `"token" is required`, `"token" must be a valid GUID`) | 400         |
| `SELFHOSTED_APP_ERROR`  | This feature is only available for self-hosted instances                            | 500         |
| `ACCOUNT_NOT_FOUND`     | ACCOUNT\_NOT\_FOUND                                                                 | 500         |
| `INTERNAL_SERVER_ERROR` | INTERNAL\_SERVER\_ERROR                                                             | 500         |

## Related

* [Rotate Service Token](/developer-docs/helpers/api-reference/rotate-service-token) – Rotate the service token with an expiration window
* [Create Admin Account](/developer-docs/helpers/api-reference/create-admin-account) – Create the first admin account (self-hosted)
* [Create Admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt) – Get an access token for admin APIs