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.

Generate API 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 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 NUA Key: Create and add a new API Key.
  5. Copy the generated key: Copy the key.

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

2. User Key​

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

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 Domain, Entity id, Single Sign-On URL and X.509 certificate of your SAML identity provider in the SAML section.

Once this is done, in the login page of the Nuclia Dashboard, users will see a Use Single Sign-On button.

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.