Skip to content
Copyright © 2022- basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

Authentication

Every request to the API must be authenticated using a valid API token and a correct X-Realm header. You can create API tokens for your organisation in the API Token section of the basebox administration panel.

Note

The REST API is an optional feature; your basebox license must cover its use. For on-premise installations, you must also ensure that the environment variable AISRV_ENABLE_REST_API is set to true.

If this is not the case, the API Token section is not displayed in the basebox admin panel.

X-Realm

The X-Realm header must be used to specify the realm (subdomain) of the organisation that created the API token. Depending on whether you are using basebox in the cloud (e.g. <yourdomain>.basebox.ai) or on-premise (i.e. self-hosted), the realm will be different:

Cloud version

The value for the X-Realm header is the subdomain of your organisation. If for example your basebox.ai domain is myorg.basebox.ai, the value for the X-Realm header would be myorg.

On-premise version

The value for the X-Realm header is usually primary. The value for your on-premise installation might differ; in this case, login to your basebox instance, open the main menu and click About basebox. The required name is displayed in the Realm row.

API Token

API tokens are base64 encoded strings that can be created by organization administrators.

Creating API Tokens

To create a new API token, follow these steps:

  1. Log in to basebox and open the administration panel.
  2. Navigate to the API Token section.
  3. Click on the Create Token button.
  4. Enter a name for your token.
  5. Click on the Create button.

The token will be displayed on the screen. Copy it and save it somewhere safe, preferably in a password manager. The token will not be displayed again, so make sure to save it securely. If you lose your token, you will need to create a new one.

API Token Usage

Include the token in the Authorization HTTP header of your requests as a bearer token:

Authorization: Bearer <token>

Example

This is a simple example using curl that shows how to use the X-Realm header and the API token:

curl -X POST \
  https://aims.basebox.ai/rest/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'X-Realm: myorg' \
  -H 'Authorization: Bearer <token>'
  -d '{
    "model": "ai.basebox.assistant",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "Hello! How are you today?"
      }
    ]
  }'