Skip to main content

Authenticating Requests

Nuclia offers several methods for authorizing API requests, each tailored to different use cases and levels of access. Here’s an overview of the main authorization methods available for interacting with the Nuclia API:

1. API key​

API keys provide access to a specific Knowledge Box and support different roles: Reader, Writer, and Manager. Api keys are organized by Service Accounts: Service account is the object that holds the role configuration, and on top of that you can create different api keys with different expirations, e.g. to implement your custom key rotations.

Generate API key​

In the Nuclia Dashboard, you can manually add or remove API Keys:

  1. Log in to the Dashboard: Access the Nuclia Dashboard with your credentials.
  2. Navigate to Your Knowledge Box: Select the Knowledge Box you want to authorize.
  3. Navigate to API Keys: In the left panel, in the Advanced menu you will find the API Keys section.
  4. Create new API Key: Create and add a new API Key.
  5. Copy the generated key: Copy the key.

API Keys will expire after 1 year. To customize this expiration date, use the API.

Use API key​

To use a API key with the API, include it in the X-NUCLIA-SERVICEACCOUNT header as a Bearer token:

GET /some-endpoint HTTP/1.1
Host: <zone>.nuclia.cloud
X-NUCLIA-SERVICEACCOUNT: Bearer YOUR-SERVICE-TOKEN

Temporal API Keys​

Temporal API keys function as short-lived tokens (maximum 10 seconds) built on top of a service account. They serve as an alternative to standard API keys in specific scenarios. One key use case is:

  • You have a client-facing application where exposing your Nuclia API key is not an option.
  • To mitigate this, you implement a proxy where users authenticate and send requests to your backend.
  • Your backend, in turn, uses the API key to communicate securely with Nuclia.

While this is a valid and secure approach, there are cases where implementing a backend proxy can be complex, and direct requests to Nuclia from the client application would be a better solucion. In such cases, the recommended workflow is:

  1. The client application requests a token from the backend.
  2. The backend, using an existing API Key, requests a temporal service account key from the Nuclia API.
  3. The client application uses this temporal key to communicate directly with the Nuclia API.

Generate API Key​

When creating your first API key, you may have noticed that multiple persistent keys can be linked to the same API key configuration. However, due to their temporary nature, temporal API keys are not persistent and can only be generated via the API.

To create a service account and key programatically, follow steps on the previous "Generate API Key section". With the resulting token you can then request a temporal api key

Generate the Temporal API Key:

curl --location 'https://<ZONE>.nuclia.cloud/api/v1/service_account_temporal_key' \
--header 'X-NUCLIA-SERVICEACCOUNT: Bearer <YOUR-SERVICE-ACCOUNT_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "ttl": 5,
    "security_groups": ["group1", "group2"]
}'

Use Tempral API Key​

These keys are effectively service account keys, so use the same header as the API keys, just take into account that the security_group presence alters the result you will get:

  • Without specifying security groups: The temporal key will function exactly like its parent API key.
  • When security groups are specified:
    • The key will be restricted to endpoints that support security group filtering—currently, the /ask endpoints.
    • The specified groups will be injected into the authorization process of your /ask request. If no matching group exists, the request will return no response.

2. User Keys​

User Keys belong to a specific user and have a short lifetime. They are recommended for trying out the nuclia developer tools or for simple scripts.

Generate and Use User Key​

This method is meant to be used from the Nuclia frontend applications but if you need it for testing purpose, you can obtain a token by going to [https://nuclia.cloud/redirect?display=token]

Then in the API calls, include it in the Authorization header as a Bearer token:

GET /some-endpoint HTTP/1.1
Host: nuclia.cloud
Authorization: Bearer YOUR-USER-KEY

If you need long-term access to any api that is not in the scope of a regular API key or a NUA Key (usage reporting APIs, at the time of writing), there's the option to create a Personal Access Token (PAT), that effectively authorizes the key to perform any action as the user who the key has been issued.

To create a PAT, you need to request it as an authenticated user

curl --location 'https://nuclia.cloud/api/v1/user/pa_tokens' \
--header 'Authorization: Bearer <YOUR-USER_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "description": "My PA token",
}'

You can create several PAT's for the same user. Expiration is optional, and by default a token lasts one year. More info on the API reference. As it is effectively a user key, you use the same Authorization header.

3. NUA Keys​

NUA Keys are designed for services that does not use NucliaDB, such as the NUA Understanding API. These keys are used to authenticate requests for zone specific APIs.

Generate NUA Key​

In the Nuclia Dashboard, you can manually add or remove NUA Keys:

  1. Log in to the Dashboard: Access the Nuclia Dashboard with your credentials.
  2. Navigate to Your Account: Go to Manage account.
  3. Navigate to NUA Keys: In the left panel you will find the NUA Keys section.
  4. Create new NUA Key: Create and save a new NUA Key.
  5. Copy the generated key: Copy and save the key.

Use NUA Key​

To use a NUA key with the API, include it in the X-NUCLIA-NUAKEY header as a Bearer token:

GET /some-endpoint HTTP/1.1
Host: <zone>.nuclia.cloud
X-NUCLIA-NUAKEY: Bearer YOUR_NUA_KEY

4. SAML​

If your organization uses SAML for authentication, you can declare your SAML identity provider in the Nuclia Dashboard:

  • go to Manage Account in the user menu in the top-right corner
  • click on Account in the side navigation bar
  • enter the Entity id, Single Sign-On URL and X.509 certificate of your SAML identity provider in the SAML section.
  • enter the Domain, that needs to match the domain of the emails you'll use to login.

Once this is done, in the login page of the Nuclia Dashboard, a Use Single Sign-On button appears just after the user enters a matching email address and switches focus on the password field input. If the button does not appear, check the domain configuration as it will probably not match the email used.

If you are using Google Worskpace, the typical configuration would be:

Google Workspace SAML configuration

Conclusion​

Choosing the appropriate authorization method depends on your use case and the scope of your workflow:

  • Use API keys when working within a Knowledge Box scope.
  • Use User Keys for testing purposes or not automated workflows.
  • Use NUA Keys when you don't need access to NucliaDB.
  • Use SAML when you want to use your organization's SAML identity provider to control access to the Nuclia Dashboard and/or to the API.

Each method ensures secure and appropriate access to the Nuclia API based on your application's needs.

warning

If you include multiple authorization headers in the same request, the request will be rejected. Ensure that only one authorization method is used per request. For example, using both a NUA Key and a API key will fail.