# Authentication

## API Authentication

Personal Access Tokens are used for API authentication and are required for use of the [Python SDK](https://github.com/dbnlAI/docs/blob/main/reference/python-sdk.md).

To create a Personal Access Token click on your profile badge in the lower left of the UI, then click on "Personal Access Token." We recommend saving this as an environment variable like `DBNL_API_TOKEN` for future use.

{% hint style="warning" %}
New tokens can be generated at any time, but old tokens cannot currently be revoked, so please remember to keep your tokens safe.
{% endhint %}

## User Authentication

The DBNL platform uses [OpenID Connect](https://openid.net/developers/how-connect-works/) or OIDC for user authentication. OIDC providers that are known to work with DBNL include:

* [Auth0](https://auth0.com/)
* [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id)
* [Okta](https://www.okta.com/)

{% hint style="warning" %}
The DBNL [Sandbox Deployment](https://docs.dbnl.com/platform/deployment/sandbox) does not use OIDC for authentication, but just a default [username/password](https://docs.dbnl.com/deployment/sandbox#authentication) for all users. For fuller authentication controls please consider a full [Deployment](https://docs.dbnl.com/platform/deployment).
{% endhint %}

### Configuration

OIDC can be configured using the following options in the DBNL Helm chart or Terraform module:

* `audience`
* `clientId`
* `issuer`
* `scopes`

Instructions on how to get those options for each provider can be found below.

{% tabs %}
{% tab title="Auth0" %}

1. Follow the [Auth0 instructions](https://auth0.com/docs/get-started/auth0-overview/create-applications/single-page-web-apps) to create a new SPA (single page application).
   1. In *Settings > Application URIs*, add the DBNL deployment domain to the list of *Allowed Callback URLs* (e.g. dbnl.mydomain.com).
2. Navigate to *Settings > Basic Information* and copy the **Client ID** as the OIDC `clientId` option.
3. Navigate to *Settings > Basic Information* and copy the **Domain** and prepend with `https://` to use as the OIDC `issuer` option (e.g. `https://my-app.us.auth0.com/`).
4. Follow the [Auth0 instructions](https://auth0.com/docs/get-started/apis/api-settings) to create a custom API.
   1. Use your DBNL deployment domain as the Identifier (e.g. dbnl.mydomain.com).
5. Navigate to *Settings > General Settings* and copy the **Identifier** as the OIDC `audience` option.
6. Set the OIDC `scopes` option to `"openid profile email"`.
   {% endtab %}

{% tab title="Microsoft Entra ID" %}

1. Follow the [Microsoft Entra ID instructions](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc) to create a new SPA (single page application) and enable OIDC.
   1. Add the DBNL deployment domain as the callback URL (e.g. dbnl.mydomain.com).
2. \[Optional] Follow the [Microsoft Entra ID instructions](https://learn.microsoft.com/en-us/entra/identity-platform/howto-restrict-your-app-to-a-set-of-users) to restrict access to certain users.
3. Navigate to *App Registrations > (Application) > Manage > API permissions* and add the Microsoft Graph **email**, **openid** and **profile** permissions to the application.\
   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXd8pbhruvYAq8a5Vu_oal3hU8fEgW0DEVuKL_uawiFlYOG8IbZh5jmT1ma0TWzGr5c3Qa9KSMmifguvCLq01bNLe5IaPBwJd9Xd_2yWpHmRmTF6hUKgZ9ScOnIo4hrb4trssuFQrIpQVYlmw76dPFS0VXpc?key=RDpRvPFm_ApGIi4n-TMN1w)
4. Navigate to *App Registrations > (Application) > Manage > Manifest* and set access token version to 2.0 with `"accessTokenAcceptedVersion": 2` .
5. Navigate to *App Registrations > (Application) > Manage > Token configuration > Add optional claim > Access > email* to add the **email** optional claim to the access token type.\
   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeoOkKeWfMlgAps3i954ZPXoqB-qGmmiilsJLa73yWUCJqPFy1QrjHQVK8bdD7BehLGFt4hvAV6CuZuCL8Ki7uMa54-UA8RoBaJf-WdFKF1EFGX6208XB8swvXBLh1lr_9jj4JEwj3eggtXqN18pWI37zFe?key=RDpRvPFm_ApGIi4n-TMN1w)
6. Navigate to *App Registrations > (Application)* and copy the *Application (client) ID* (`APP_ID`) to be used as the OIDC `clientId` and OIDC `audience` options.
7. Set the OIDC `issuer` option to `https://login.microsoftonline.com/{APP_ID}/v2.0` .
8. Set the OIDC `scopes` option to `"openid email profile {APP_ID}/.default"`.
   {% endtab %}

{% tab title="Okta" %}

1. Follow the [Okta instructions](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) to create a new SPA (single page application) and enable OIDC.
   1. Set the *Sign-in redirect URIs* to your DBNL domain (e.g. dbnl.mydomain.com)
2. Navigate to *General > Client Credentials* and copy the Client ID to be used as the OIDC `clientId` option.
3. Navigate to *Sign on > OpenID Connect ID Token* and copy the *Issuer URL* to be used as the OIDC `issuer` and OIDC `audience` options.
4. Set the OIDC `scopes` option to `"openid email profile"` .
   {% endtab %}
   {% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dbnl.com/platform/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.