1.1. Authentication Methods¶
1.1.1. Overview¶
This document outlines the two supported authentication methods for accessing the Ngenea Hub API: JWT (JSON Web Tokens) and Client Keys (API Keys).
It provides clear instructions on how to obtain, use, and manage these tokens and keys, including examples for both command-line usage and Swagger UI.
1.1.2. API Reference Location¶
All endpoints, parameters, and schemas can be explored through the interactive API documentation available at:
http(s)://<your-hub-address>/api/docs/
Note
Replace your-hub-address with the actual IP address or domain of your Ngenea Hub instance.
1.1.3. JWT Authentication - Using Curl¶
A JWT (JSON Web Token) is a compact, secure way to represent user identity. It is commonly used for authentication. After logging in with your credentials, the server provides a token that confirms your identity, allowing you to make future API requests without resending your username and password each time.
To obtain a JWT, send a POST request to the authentication endpoint using curl:.
Example Format
curl -X 'POST' \
'http://<your-hub-address>/api/auth/token/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"username": "<username>",
"password": "<password>"
}' |jq
Note
The curl command works across different operating systems, but with slight differences in usage.
On Linux and macOS, curl is typically pre-installed and can be run directly in the terminal without any setup.
On Windows 10 and later, curl is also built into Command Prompt (CMD) and PowerShell, you can use GIT BASH as well.
If you’re using an older version of Windows, you may need to download curl from the official site: curl for Windows .
Note
jq is a command-line tool used to easily parse and extract specific data from JSON responses, making it simpler to handle API outputs like JWT tokens.
It comes pre-installed on many Linux distributions and macOS, otherwise, it must be installed manually as per Download jq , while on Windows you can install it via package managers like Chocolatey, Winget, or use it in WSL - check your installed version anytime with jq -version.
The server responds with two tokens:
An access token, which is short-lived (1 hour) and should included in each request to authenticate the user.
A refresh token, which lasts longer (1 day) and is used to obtain a new access token when the current one expires.
These tokens are returned in a JSON format like this:
{
"access": "your_access_token_here",
"refresh": "your_refresh_token_here"
}
Using JWT Access Token for API Requests
When making authenticated requests using the JWT token, include it in the Authorization header using the Bearer scheme.
Bearer <JWT_Access_Token>
Example: Hub Health
curl -X 'GET' \
'http://<your-hub-address>/api/health/' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <JWT_Access_Token> '|jq
Example Response:
{
"overall_health": "ok",
"hub_status": {
"health": "ok"
},
"site_status": [
{
"site": "siteA",
"health": "ok",
"nodes": [
{
"name": "siteA",
"health": "ok",
"online": true,
"has_default_queue": true,
"last_heartbeat": "2025-06-02T15:25:18.562813+00:00",
"worker_version": "2.6.0",
"ngenea_version": "1.31.0",
"analytics_version": "2.7.1",
"search_version": "1.2.0"
}
],
"queues": [
{
"name": "default",
"health": "ok",
"online": true,
"last_heartbeat": "2025-06-02T15:25:18.562813+00:00"
}
]
},
}
Using Refresh Tokens to Obtain New Access Tokens
As mentioned earlier, access tokens expire after 1 hour, while refresh tokens expire after 1 day. When you use an expired access token, you’ll receive an HTTP 401 Unauthorized or HTTP 403 Forbidden error.
In this situation, you should request a new access token using the /api/auth/token/refresh/ endpoint with your refresh token.
Example request using curl:
$ curl -s -X POST 'http://localhost:8000/api/auth/token/refresh/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{"refresh": "<Refresh_Token>"}' | jq -r
Response :
{
"access": <new_access_token>,
}
1.1.4. Client Key Authentication¶
A client key (or API key) is a long-lived, unique token used to authenticate and authorize applications or scripts to access an API. Unlike short-lived tokens like JWTs, client keys typically do not expire unless manually revoked, making them ideal for automated processes, integrations, and services that require persistent access without frequent re-authentication.
To generate a client key, send a POST request to the /api/auth/clientkeys/ endpoint with a descriptive name for the key, including your JWT access token in the Authorization header:
You can either use the access token obtained above or generate a new one using the following command:
export JWT_TOKEN=$(curl -s -X POST 'http://localhost:8000/api/auth/token/' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"username": "<username>", "password": "*******"}' | jq -r .access)
echo $JWT_TOKEN
Note
Why is this different ?
The difference lies in improving user flow and convenience:
export JWT_TOKEN=...stores the access token in an environment variable calledJWT_TOKEN. This makes the token easily accessible within the current shell session and any child processes (such as scripts or subsequent commands).The use of
jq -r .accessextracts only the raw access token (without quotes) from the JSON response.echo $JWT_TOKENprints the token to the terminal, confirming that it was successfully retrieved and saved.
This approach simplifies usage by allowing the token to be reused easily in subsequent commands. (These commands are for Linux based systems)
Example Format - Client Key Creation
curl -s -X POST 'http://10.201.2.224:8000/api/auth/clientkeys/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer $JWT_TOKEN"
-d '{"name": "your_key"}' | jq '.'
Example Response
{
"url": "http://localhost:8000/api/auth/clientkeys/10/",
"id": 10,
"name": "your_key",
"api_key": "YOUR_API_KEY"
}
Using Client Key for API Requests
Once you have the client key, you can use it for API access by including it in the Authorization header using the Api-Key scheme.
Api-Key <api_key>
Example-Jobs
export API_KEY=YOUR_API_KEY
curl -s -X GET 'http://localhost:8000/api/jobs/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Api-Key $API_KEY" | jq
Note
Replace YOUR_API_KEY with the actual API key string returned during creation.
Example Response
{
"count": 6,
"next": null,
"previous": null,
"results": [
{
"url": "http://my-hub:8000/api/jobs/1/",
"id": 1,
"workflow": null,
"fields": null,
"created": "2025-05-14T13:00:40.153027Z",
"started": "2025-05-14T13:00:48.166288Z",
"completed": "2025-05-14T13:00:49.829041Z",
"runtime": 1.662753,
"state": "SUCCESS",
"site": "siteA",
"queue": null,
"owner": {
"type": "user",
"id": 1,
"name": "pixit"
},
"discovery": null,
"dir_walk_complete": true,
"is_settings_job": true,
"friendly_name": "Populating/Updating settings from site siteA",
"progress": null
},
{
"url": "http://my-hub:8000/api/jobs/2/",
"id": 2,
"workflow": null,
"fields": null,
"created": "2025-05-14T13:02:14.395013Z",
"started": "2025-05-14T13:02:18.294664Z",
"completed": "2025-05-14T13:02:19.611492Z",
"runtime": 1.316828,
"state": "SUCCESS",
"site": "siteB",
"queue": null,
"owner": {
"type": "user",
"id": 1,
"name": "pixit"
},
],
"owners": [
{
"type": "user",
"name": "hubadmin",
"id": 2
},
{
"type": "user",
"name": "pixit",
"id": 1
},
{
"type": "system",
"name": "System",
"id": -2
},
{
"type": "unknown",
"name": "Unknown",
"id": -1
}
]
}
Revoking a Client Key
Client keys can be revoked at any time. To do this, you must send a DELETE request to the URL of the specific client key, using a valid JWT for authentication.
Example Format (Revoking API Key)
curl -X DELETE
'http(s)://<your-hub-address>/api/auth/clientkeys/<key-id>/' \
-H "Authorization: Bearer $JWT_TOKEN"
Note
Replace key-id with the numerical ID of the client key you wish to delete.
Once deleted, the API key will no longer grant access to any API resources.
1.1.5. Key Differences Between JWT and API Keys¶
JWT tokensconsist of an access token that expires after 1 hour and a refresh token that allows you to obtain a new access token without re-entering user credentials. The refresh token itself expires after 1 day.API keysdo not expire automatically and do not require refreshing. They remain valid until manually revoked or deleted.
1.1.6. JWT Authentication - Using Swagger UI¶
Swagger UI provides a visual interface to test API endpoints easily, including authentication flows.
Open Swagger UI: Go to your Swagger API documentation, typically available at:
http(s)://<your-ngenea-hub-host>/api/docs/
This opens the interactive Swagger UI interface for exploring and testing the API.
Authenticate via /auth/token/ Endpoint: This is the endpoint to obtain your access and refresh JWT tokens.
Look for: POST/api/auth/token/
Execute the request:
Click the
POST/auth/token/ to expand it.Click “Try it out”.
In the
Request body, input your credentials in this format:
{
"username": "your_username",
"password": "your_password"
}
Click “Execute”.
Response: If successful, you’ll receive a JSON response like:
{
"access": "your_access_token",
"refresh": "your_refresh_token"
}
Authorize the Access Token
To use the access token for other endpoints: Click the “Authorize” button (top right in Swagger UI).
In the popup, enter your token in this format:
Bearer your_access_token
Click “Authorize”, then “Close”.
Now, all subsequent API requests in Swagger UI will include this token.
Refreshing Expired Access Tokens
Access tokens expire after 1 hour. Use the refresh token to get a new access token.
Find the endpoint: POST/api/auth/token/refresh/
Execute the request:
Expand the endpoint.
Click “Try it out”.
Input:
{
"refresh": "your_refresh_token"
}
Click “Execute”.
Response: You’ll receive a new access token:
{
"access": "new_access_token"
}
Use the Authorize button again to replace the old access token with this new one.
1.1.7. Generate a Client Key - Using Swagger UI¶
Note
Make sure you’ve already completed JWT token generation and authorization via the /auth/token/ endpoint and used the Authorize button in Swagger UI to authenticate.
This is required before accessing protected endpoints like /auth/clientkeys/.
Locate the /auth/clientkeys/ Endpoint.
In Swagger UI, search or scroll down to find:
POST/api/auth/clientkeys/Click it to expand its details.
Click “Try it out” button to make the request body editable.
Fill in the Request Body: Enter the necessary parameters.
A basic example:
{
"name": "my-client-key"
}
Once your request is ready, click Execute to send it.
If successful, you’ll receive a response similar to:
{
"url": "https://<your-ngenea-hub-host>/api/auth/clientkeys/0/",
"id": 0,
"name": "my-client-key",
"api_key": "generated_client_api_key"
}
Note
Store the api_key securely, as it is not retrievable again through the API.
Authorize the API Key
To use the API key for other endpoints: Click the “Authorize” button (top right in Swagger UI).
In the popup, enter your
API keyin the required format.
Example format:
Api-Key <your_api_key>
Click “Authorize”, then “Close”.
Now, all subsequent API requests in Swagger UI will include this API key automatically.