1.2. API Endpoints - User and Access Management¶

1.2.1. Introduction¶

This section provides detailed documentation for all available Ngenea Hub API endpoints. Each endpoint is a specific URL path designed to perform a distinct function, such as retrieving analytics, managing client keys, or interacting with job data. Whether you’re listing resources, updating configurations, or triggering actions, each endpoint follows standard HTTP conventions and returns structured JSON responses.

The purpose of this guide is to help you understand exactly how each API endpoint works, including:

What the endpoint does and when to use it
Required and optional parameters (path, query, or body)
Example curl requests for real-world usage
Sample responses with explanations of each field

Each endpoint is broken down into clearly labeled sections to help both beginners and experienced developers quickly understand how to use it effectively.

Note

While the Ngenea API is intended for internal tools and authorized automation within secured environments.

All API calls require proper authentication using either JWT access tokens or Client API Keys.

Refer to the link to know more about the authentication methods.

1.2.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.2.3. Auth - Authentication¶

1.2.3.1. `GET` /auth/clientkeys/¶

Description

Retrieves a paginated list of client API keys. This endpoint is typically used by administrators or authorized users to view all API keys that have been generated for client-side access to the hub. It is useful in scenarios where API access needs to be managed, audited, or reviewed for security purposes.

For example, developers or administrators might use this endpoint to list keys tied to specific users, monitor which keys are active, or integrate this data into dashboards or automated scripts. Each key entry includes its name, the associated user, and a URL that can be used to perform further operations such as updating or deleting the key.

This endpoint does not expose actual client keys, and there is no way to retrieve a client key once it has been created.

Request Parameters

Name	Type	Required	Description
`page`	integer	No	Page number of the result set. Defaults to 1 if not specified.
`page_size`	integer	No	Number of results to return per page. Must be between 20 and 100. Use 0 to return all results without pagination. Defaults to 20 if not specified or below the minimum.

Example Request

curl -X GET \
  'http://<your-server>/api/auth/clientkeys/?page=1' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "http://<your-server>/api/auth/clientkeys/5/",
      "id": 5,
      "name": "client_key_1",
      "user": "hubadmin"
    },
    {
      "url": "http://<your-server>/api/auth/clientkeys/11/",
      "id": 11,
      "name": "key_2",
      "user": "hubadmin"
    },
    ...
  ]
}

Response Fields

Field	Type	Description
`count`	integer	Total number of client keys available.
`next`	string/null	URL to the next page of results (if any).
`previous`	string/null	URL to the previous page of results (if any).
`results`	array	List of client key objects. Each object includes:
`results[].url`	string	API URL to access this specific client key.
`results[].id`	integer	Unique identifier of the client key.
`results[].name`	string	User-defined name for the client key.
`results[].user`	string	Username associated with this client key.

1.2.3.2. `GET` /auth/clientkeys/{id}/¶

Description

Retrieves the details of a specific client API key by its unique ID. This endpoint is useful for viewing the metadata of an individual client key such as its name, associated user, and API URL for further operations.

Request Parameter

Name	Type	Required	Description
`id`	string	Yes	The unique identifier (ID) of the client key to retrieve.

Example Request

curl -X GET \
  'http://<your-server>/api/auth/clientkeys/7/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "url": "http://<your-server>/api/auth/clientkeys/7/",
  "id": 7,
  "name": "new_key_0206",
  "user": "hubadmin"
}

Response Fields

Field	Type	Description
`url`	string	Full API endpoint URL for this client key.
`id`	integer	Unique ID of the client key.
`name`	string	User-defined name for the client key.
`user`	string	Username associated with the key (e.g., the creator or owner).

1.2.3.3. `DELETE` /auth/clientkeys/{id}/¶

Description

This endpoint permanently deletes a specific client API key by its unique ID. Use this operation to remove keys that are no longer needed or have been compromised.

Deleted keys cannot be recovered, so use with caution.

Request Parameter

Name	Type	Required	Description
`id`	string	Yes	The unique identifier (ID) of the client key to retrieve.

Example Request

curl -X DELETE \
  'http://<your-server>/api/auth/clientkeys/2/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>'

Successful Response

HTTP Status Code: 204 No Content

This means the key was successfully deleted.

There is no response body when deletion is successful.

1.2.3.4. `GET` /api/auth/token/publickey/¶

Description

This API endpoint gives you the public key that is used to verify the signature on a JWT (JSON Web Token).

When a user logs in, the server creates a JWT and signs it using a private key. This signed token is then sent to the client (like a web app or mobile app).

Other systems or services (like your backend or microservices) can then use this public key to check:

That the token really came from the authentication server, and
That it has not been changed or tampered with.

This process is called token verification.

Using the public key like this is especially helpful in systems where different parts (like microservices) need to validate tokens independently, without needing to contact the main authentication server every time.

Request Parameter

This endpoint does not require any query or path parameters.

Example Request

curl -X GET \
  'http://<your-server>/api/auth/token/publickey/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "keys": [
    {
      "alg": "RS256",
      "e": "AQAB",
      "kid": "<key-id>",
      "kty": "RSA",
      "n": "<modulus-value>",
      "use": "sig"
    }
  ]
}

Response Fields

Field	Type	Description
`alg`	string	The algorithm used for the key (e.g., RS256).
`e`	string	Public exponent of the RSA key, encoded in Base64URL.
`kid`	string	Key ID — a unique identifier for the key.
`kty`	string	Key type (usually RSA).
`n`	string	The RSA public key modulus, Base64URL-encoded.
`use`	string	How the key is used (e.g., `sig` for signature verification).

1.2.3.5. `POST` /api/auth/token/verify/¶

Description

This API endpoint is used to verify the validity of a JWT (JSON Web Token).

It checks three main things:

The token has not expired.
The user linked to the token exists in the system.
The user is active (i.e., not disabled or deleted).

This is useful for confirming that a token should still be trusted before allowing access to a protected resource.

Resquest Parameters

Field	Type	Required	Description
`type`	string	Yes	The type of token (e.g., `"access"` or `"refresh"`).
`token`	string	Yes	The JWT you want to verify.

Example Request

curl -X POST \
  'http://<your-server>/api/auth/token/verify/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "access",
    "token": "<your-jwt-token>"
  }'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 2,
  "username": "exampleuser",
  "first_name": "",
  "last_name": "",
  "email": "",
  "is_active": true,
  "is_superuser": false,
  "is_staff": false,
  "last_login": "2025-06-11T12:17:53.724142Z",
  "date_joined": "2025-05-23T10:57:26.219710Z",
  "groups": [1],
  "user_permissions": []
}

Response Fields

Field	Type	Description
`id`	integer	Unique identifier of the user in the system.
`username`	string	The username associated with the token.
`first_name`	string	User’s first name (empty if not provided).
`last_name`	string	User’s last name (empty if not provided).
`email`	string	Email address of the user (empty if not provided).
`is_active`	boolean	Indicates whether the user account is currently active.
`is_superuser`	boolean	Indicates if the user has superuser (full admin) privileges.
`is_staff`	boolean	Indicates whether the user can log into the admin site.
`last_login`	string (ISO 8601)	Timestamp of the last time the user logged in.
`date_joined`	string (ISO 8601)	Timestamp of when the user account was created.
`groups`	array of integers	List of group IDs that the user belongs to.
`user_permissions`	array	List of permission identifiers assigned to the user (empty if none).
`password`	string	Hashed version of the user’s password (internal use – do not expose).

1.2.4. Users¶

In the Hub system, users represent individuals who have access to the platform through a secure login. Each user has a profile containing basic information such as their name, email, and group membership. The system defines two distinct user types:

Admins: These users have full access to all system features and administrative functions. They can manage other users, configure settings, and generate or revoke API keys.
Read-Only Users: These users have restricted access and can only view data within the Hub. They cannot modify settings, manage users, or perform administrative tasks.

Understanding user roles is essential for managing access control and integrating with the Users API. Only Admins are permitted to perform operations that alter user data or system configuration.

username: A required field (max 150 characters) that can include alphanumeric characters, underscores, and some symbols like @, +, ., and -.
first_name / last_name: Optional fields for the user’s first and last name (max 150 characters).
email: Optional field for the user’s email address.
password: Required field, with restrictions on which characters can be used.

1.2.4.1. `GET` /users/¶

Description

The /users/ endpoint retrieves a list of users registered in the Hub system. This endpoint is primarily accessible to Admin users, who can use it to manage or monitor users within the platform. It supports pagination and returns detailed user information, including group membership.

Request Parameters

Refer to the Request Parameters under GET /auth/clientkeys/ to learn more.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/users/?page=1' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2,
      "url": "http://your-hub-address:8000/api/users/hubadmin/",
      "username": "hubadmin",
      "first_name": "",
      "last_name": "",
      "email": "",
      "is_active": true,
      "last_login": "2025-06-24T12:59:29.823039Z",
      "date_joined": "2025-05-23T10:57:26.219710Z",
      "groups": [
        {
          "id": 1,
          "url": "http://your-hub-address:8000/api/groups/1/",
          "name": "Administrators"
        }
      ],
      "profile": null,
      "nas_user": null
    },
    {
      "id": 1,
      "url": "http://your-hub-address:8000/api/users/pixit/",
      "username": "pixit",
      "first_name": "",
      "last_name": "",
      "email": "jenkins@example.com",
      "is_active": true,
      "last_login": "2025-05-14T13:07:57.656518Z",
      "date_joined": "2025-05-14T12:06:59.927211Z",
      "groups": [
        {
          "id": 1,
          "url": "http://your-hub-address:8000/api/groups/1/",
          "name": "Administrators"
        }
      ],
      "profile": null,
      "nas_user": null
    }
  ]
}

Response Fields

Field	Type	Description
`count`	integer	Total number of users in the system.
`next`	string/null	URL to the next page of results, or `null` if there are no more pages.
`previous`	string/null	URL to the previous page of results, or `null` if on the first page.
`results`	array	List of user objects. Each object contains detailed information about a user.

Each user object in results includes:

Field	Type	Description
`id`	integer	Unique identifier for the user.
`url`	string	API endpoint URL for the individual user.
`username`	string	User’s login name.
`first_name`	string	User’s first name (can be empty).
`last_name`	string	User’s last name (can be empty).
`email`	string	User’s email address.
`is_active`	boolean	Indicates whether the user account is active.
`last_login`	datetime	Timestamp of the user’s last login.
`date_joined`	datetime	Timestamp of when the user account was created.
`groups`	array	List of groups the user belongs to. Typically used to determine user roles.
`profile`	object/null	Reserved for extended profile information. Currently `null`.
`nas_user`	object/null	Reserved for NAS-related user info. Reserved implies the field is unused, which means `null` unless the user is NAS enabled.

1.2.4.2. `POST` /users/¶

Description

This endpoint creates a new user in the Hub system. Only Admin users are authorized to create new user accounts.

Users can be assigned to one or more groups and optionally provided with extended profile details. By default, the new user is active. The nas_user field is included in the response and can be left null unless your system integrates with a NAS (Network-Attached Storage) component.

Request Parameters

Name	Type	Required	Description
`username`	string	Yes	The unique username for the new user.
`password`	string	Yes	The password for the user. It will be securely hashed in the response.
`first_name`	string	No	User’s first name.
`last_name`	string	No	User’s last name.
`email`	string	No	User’s email address.
`groups`	array	Yes	List of group names the user should belong to (e.g., `["Users"]`, `["Administrators"]`).
`profile`	object	No	Optional user profile with extended info. See fields below.

Profile Subfields

Field	Type	Description
`phone`	string	User’s phone number.
`timezone`	string	User’s preferred timezone. e.g. `Europe/London`
`country`	string	User’s country.
`department`	string	Department to which the user belongs.
`line_manager`	string	Name of the user’s line manager.
`default_site`	integer	ID of the default site assigned to the user.
`home_site`	integer	ID of the user’s home site.

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/users/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "Example2",
    "password": "*********",
    "first_name": "Example",
    "last_name": "User",
    "email": "user@gmail.com",
    "groups": ["Users"],
    "profile": {
      "phone": "12345678",
      "timezone": "string",
      "country": "string",
      "department": "string",
      "line_manager": "string",
      "default_site": 1,
      "home_site": 1
    }
  }'

Successful Response

HTTP Status Code: 201 Created

Content-Type: application/json

Example Response

{
  "username": "Example2",
  "password": "********",
  "first_name": "Example",
  "last_name": "User",
  "email": "user@gmail.com",
  "groups": ["Users"],
  "profile": {
    "phone": "12345678",
    "timezone": "string",
    "country": "string",
    "department": "string",
    "line_manager": "string",
    "default_site": 1,
    "home_site": 1
  },
  "nas_user": null
}

Response Fields

Note

The response fields are described under the request parameters section above. Please refer to that section for details.

1.2.4.3. `POST` /users/change_password/¶

Description

This endpoint allows an authenticated user to securely change their password. The request must include the user’s current (old) password and the new password they wish to set.

Only the currently logged-in user can change their own password using this endpoint. Admin users must use the user management interface or a different admin-level endpoint to reset other users’ passwords.

Request Parameters

Name	Type	Required	Description
old_password	string	Yes	The user’s current password.
new_password	string	Yes	The new password to set. Must meet password policies.

Note

When creating or changing a password, the following rules must be met:

Must be at least 8 characters long
Cannot be too similar to the username
Must include at least one digit
Must include at least one uppercase letter
Must include at least one special character (e.g., !@#$%^&*)

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/users/change_password/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "old_password": "*********",
    "new_password": "**********"
  }'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "message": "password successfully changed"
}

Error Response

HTTP Code	Description	Example Message
400	Invalid old password or weak new password	`{"old_password": ["Incorrect password."]}` or `{"new_password": ["This password is too short."]}`
401	Unauthorized (missing or invalid token)	`{"detail": "Authentication credentials were not provided."}`

1.2.4.4. GET /users/{username}/¶

This endpoint retrieves detailed information for a specific user identified by their username. It returns the user’s basic info, group memberships, profile details, and NAS user reference (if applicable).

This endpoint is accessible to Admin users for reviewing user configurations, or by users retrieving their own account data (depending on permissions).

Request Parameters

Name	Type	Required	Description
username	string	Yes	The username of the user to retrieve. Must match pattern: `[\w\.\+\-_@]+`

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/users/Example/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 4,
  "url": "http://your-hub-address:8000/api/users/Example/",
  "username": "Example",
  "first_name": "Example",
  "last_name": "User",
  "email": "user@gmail.com",
  "is_active": true,
  "last_login": null,
  "date_joined": "2025-06-25T11:53:37.572849Z",
  "groups": [
    {
      "id": 2,
      "url": "http://your-hub-address:8000/api/groups/2/",
      "name": "Users"
    }
  ],
  "profile": {
    "phone": "string",
    "timezone": "string",
    "country": "string",
    "department": "string",
    "line_manager": "string",
    "default_site": 1,
    "home_site": 1
  },
  "nas_user": null
}

Response Fields

To view the information related to response fields and profile subfields , refer to GET & POST Users endpoint.

1.2.4.5. `PATCH` /users/{username}/¶

Description

This endpoint allows partial updates to an existing user’s information using their username. You can update any combination of the following fields: basic user details, group membership, password, and extended profile information. This endpoint also allows you to PATCH NAS user settings, such as enabling or disabling NAS access.

Only Admin users or authorized users (e.g., self-edit under permissions) can perform this action.

Request Path Parameters

Name	Type	Required	Description
username	string	Yes	The username of the user to update.

Request Body Parameters (Partial Update)

Name	Type	Description
password	string	(Optional) New password. Must comply with Password Requirements.
first_name	string	(Optional) Updated first name.
last_name	string	(Optional) Updated last name.
email	string	(Optional) Updated email address.
groups	array	(Optional) List of group names to which the user should belong.
profile	object	(Optional) User’s profile data. See subfields below.

Note

To view the information related to profile subfields , refer to POST Users endpoint.

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/users/Example2/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "*******",
    "first_name": "Updated",
    "last_name": "Info",
    "email": "user@example.com",
    "groups": ["Users"],
    "profile": {
      "phone": "string",
      "timezone": "string",
      "country": "string",
      "department": "string",
      "line_manager": "string",
      "default_site": 1,
      "home_site": 1
    }
  }'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "first_name": "Updated",
  "last_name": "Info",
  "email": "user@example.com",
  "groups": [
    "Users"
  ],
  "profile": {
    "phone": "string",
    "timezone": "string",
    "country": "string",
    "department": "string",
    "line_manager": "string",
    "default_site": 1,
    "home_site": 1
  },
  "nas_user": null
}

Response Fields

The response fields are the same as the request parameters. Please refer to the section above for a better understanding.

1.2.4.6. `DELETE` /users/{username}/¶

Description

This endpoint permanently deletes a user from the system based on their username.

Only users with Administrator privileges can perform this action. Once deleted, the user account cannot be recovered unless the system provides a separate restore or archival mechanism.

Request Parameters

Name	Type	Required	Description
username	string	Yes	The username of the user to delete. Must match pattern: `[\w\.\+\-_@]+`

Example Request

curl -X 'DELETE' \
  'http://your-hub-address:8000/api/users/Example2/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 204 No Content

Content-Type: None

Body: Empty

This status code indicates that the user was successfully deleted. No response body is returned.

Note

This action cannot be undone. Make sure the user data is no longer needed or has been backed up before deletion.
If the specified username does not exist, the API may return a 404 Not Found error.
System-protected users (like default admin accounts) might be restricted from deletion, depending on implementation.

1.2.4.7. `POST` /users/{username}/activate/¶

Description

This endpoint activates a user account identified by the provided username. Activation sets the user’s is_active flag to true, allowing them to log in and access the system, assuming they meet other authentication requirements.

Request Parameters

Name	Type	Required	Description
username	string	Yes	The username of the user to delete. Must match pattern: `[\w\.\+\-_@]+`

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/users/Example3/activate/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -d ''

Successful Response

HTTP Status Code: 201 Created

Content-Type: application/json

Description: Returns the full user object with is_active set to true.

Example Response

{
  "id": 6,
  "url": "http://your-hub-address:8000/api/users/Example3/",
  "username": "Example3",
  "first_name": "Example",
  "last_name": "User",
  "email": "",
  "is_active": true,
  "last_login": null,
  "date_joined": "2025-06-25T12:01:34.447630Z",
  "groups": [
    {
      "id": 2,
      "url": "http://your-hub-address:8000/api/groups/2/",
      "name": "Users"
    }
}

Response Fields

The response fields are identical to those returned by the GET /users/ endpoint. Please refer to the section above for more details.

1.2.4.8. `POST` /users/{username}/deactivate/¶

Description

This endpoint deactivates a user account identified by the username parameter. Deactivation sets the is_active field of the user to false, preventing login or API access.

Useful for managing user access without permanently deleting accounts.

Request Parameters

Name	Type	Required	Description
username	string	Yes	The username of the user to delete. Must match pattern: `[\w\.\+\-_@]+`

Example Request

curl -X 'POST' \
  'http://10.201.2.224:8000/api/users/Example3/deactivate/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -d ''

Successful Response

HTTP Status Code: 201 Created

Content-Type: application/json

Description: Returns the full user object with is_active set to false.

Example Response

{
  "id": 6,
  "url": "http://your-hub-address:8000/api/users/Example3/",
  "username": "Example3",
  "first_name": "Example",
  "last_name": "User",
  "email": "",
  "is_active": false,
  "last_login": null,
  "date_joined": "2025-06-25T12:01:34.447630Z",
  "groups": [
    {
      "id": 2,
      "url": "http://your-hub-address:8000/api/groups/2/",
      "name": "Users"
    }
  ],
  "profile": {
    "phone": "12345678",
    "timezone": "string",
    "country": "string",
    "department": "string",
    "line_manager": "string",
    "default_site": 1,
    "home_site": 1
  },
  "nas_user": null
}

Response Fields

Please refer to PATCH /users/{username}/ response fields.

1.2.5. My Permissions¶

The /my-permissions/ endpoint allows an authenticated user to view all permissions assigned to them within the Ngenea Hub. These permissions may come from group memberships, direct assignments, or object-level grants.

The response includes details such as permission ID, name, application label, codename, and the associated model. This endpoint is strictly limited to the requesting user’s own permissions and does not expose permissions of other users.

1.2.5.1. GET /my-permissions/¶

Description

This endpoint allows the authenticated user to view only their own permissions in the Ngenea Hub.

It returns all permissions the user has through:

Group membership (group_permissions)
Direct assignment (user_permissions)
Object-level permissions (group_object_permissions, user_object_permissions)

Note

Users cannot view permissions of other users via this endpoint.

Request Parameters: None

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/my-permissions/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "group_permissions": [
    {
      "id": 290,
      "name": "Can add log entry",
      "app_label": "admin",
      "codename": "add_logentry",
      "model": "logentry"
    },
    {
      "id": 2,
      "name": "Can add alert",
      "app_label": "alerts",
      "codename": "add_alert",
      "model": "alert"
    }
  ],
  "user_permissions": [],
  "group_object_permissions": [],
  "user_object_permissions": []
}

Response Fields

Field	Type	Description
`group_permissions`	array of objects	Permissions inherited through the user’s group(s)
`user_permissions`	array of objects	Permissions assigned directly to the user
`group_object_permissions`	array	Object-level permissions via group (if any)
`user_object_permissions`	array	Object-level permissions assigned directly (if any)

Each permission object contains:

Subfield	Type	Description
`id`	integer	Unique identifier of the permission
`name`	string	Descriptive name of the permission
`app_label`	string	Application label (e.g., `"admin"`)
`codename`	string	Permission codename used internally
`model`	string	Model associated with the permission

1.2.6. Permissions¶

1.2.6.1. `GET` /permissions/¶

Description

The /permissions/ endpoint in Ngenea Hub provides a comprehensive list of all system-wide permissions configured in the backend. This endpoint is typically used by administrators, integrators, or role-management interfaces to list available permissions that can be assigned to users or groups within Ngenea Hub.

Note

This API returns all possible permissions in Ngenea Hub, not just those granted to the requesting user. To see permissions specific to the logged-in user, use the /my-permissions/ endpoint.

Request Parameters

Name	Type	Required	Description
`page`	integer	No	Page number of the result set. Defaults to 1 if not specified.
`page_size`	integer	No	Number of results to return per page. Must be between 20 and 100. Use 0 to return all results without pagination. Defaults to 20 if not specified or below the minimum.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/permissions/?page=1&page_size=20' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "count": 349,
  "next": "http://your-hub-address:8000/api/permissions/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Can view health endpoint",
      "app_label": "filebrowser",
      "codename": "view_health",
      "model": "node"
    },
    {
      "id": 2,
      "name": "Can add alert",
      "app_label": "alerts",
      "codename": "add_alert",
      "model": "alert"
    },
    {
      "id": 3,
      "name": "Can change alert",
      "app_label": "alerts",
      "codename": "change_alert",
      "model": "alert"
    }
    // ... more permissions
  ]
}

Response Fields

Field	Type	Description
`count`	integer	Total number of available permissions
`next`	string / null	URL to the next page of results, if applicable
`previous`	string / null	URL to the previous page of results, if applicable
`results`	array of objects	List of permission objects for the current page or result set

Each permission object contains:

Subfield	Type	Description
`id`	integer	Unique ID of the permission
`name`	string	Descriptive, human-readable name
`app_label`	string	Application/module the permission belongs to
`codename`	string	Internal codename used for logic checks
`model`	string	Model name the permission applies to

1.2.6.2. `GET` /permissions/{id}/¶

Description

This endpoint retrieves detailed information about a specific permission in Ngenea Hub by its unique ID.

Request Parameters

Name	Type	Location	Required	Description
`id`	string	path	Yes	The unique ID of the permission to retrieve

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/permissions/7/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 7,
  "name": "Can change bucket",
  "app_label": "external_targets",
  "codename": "change_bucket",
  "model": "bucket"
}

Response Fields

Please refer to the response fields section under GET /permissions/.

1.2.7. Groups¶

In Ngenea Hub, groups are fundamental for organizing users and managing their access to various Sites and Spaces. Groups allow administrators to define roles and permissions for multiple users at once, ensuring efficient access control across the system. By categorizing users into different groups, Hub administrators can easily assign read-only access, administrative rights, or specific permissions based on the group a user belongs to.

Ngenea Hub comes with default groups such as Administrators and Users, with predefined roles. However, custom groups can also be created to meet specific organizational needs. When integrated with LDAP or Active Directory (AD), group memberships can be automatically synced, allowing external directory users to inherit group-based permissions in Ngenea Hub.

Note

Refer to Groups and Users to learn more about groups.

1.2.7.1. `GET` /groups/¶

Description

The GET /groups/ endpoint allows users to retrieve a paginated list of groups in the Ngenea Hub. This endpoint provides information about each group, including the group name, description, associated users, and the permissions assigned to the group.

Request Parameters

Name	Type	Required	Description
`page`	integer	No	Page number of the result set. Defaults to 1 if not specified.
`page_size`	integer	No	Number of results to return per page. Must be between 20 and 100. Use 0 to return all results without pagination. Defaults to 20 if not specified or below the minimum.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/groups/?page=1' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

This request retrieves the first page of groups, with the default page size of 20.

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Administrators",
      "users": [
        {
          "username": "pixit",
          "first_name": "",
          "last_name": "",
          "email": "jenkins@example.com",
          "date_joined": "2025-05-14T12:06:59.927211Z",
          "last_login": "2025-05-14T13:07:57.656518Z"
        },
        {
          "username": "hubadmin",
          "first_name": "",
          "last_name": "",
          "email": "",
          "date_joined": "2025-05-23T10:57:26.219710Z",
          "last_login": "2025-07-04T14:17:23.449154Z"
        }
      ],
      "description": "Default group for users with administrative access",
      "permissions": [290, 291, 292, 293,],
      "object_permissions": [],
      "nas_group": null
    },
    {
      "id": 2,
      "name": "Users",
      "users": [
        {
          "username": "Test",
          "first_name": "Test",
          "last_name": "User",
          "email": "test@gmail.com",
          "date_joined": "2025-06-25T11:43:39.651419Z",
          "last_login": null
        },
        {
          "username": "Example",
          "first_name": "Example",
          "last_name": "User",
          "email": "user@gmail.com",
          "date_joined": "2025-06-25T11:53:37.572849Z",
          "last_login": null
        }
      ],
      "description": "Default group for users with read-only access",
      "permissions": [305, 17, 109, 117,],
      "object_permissions": [],
      "nas_group": null
    },
    {
      "id": 3,
      "name": "Test",
      "users": [],
      "description": null,
      "permissions": [305, 17, 109, 117, 113, 26, 29,],
      "object_permissions": [],
      "nas_group": {"gid": 100000}
    }
  ]
}

Response Fields

Group List Response Fields

Field Name	Description	Type	Example
`count`	The total number of groups available.	Integer	3
`next`	URL to the next set of results (if any).	String or null	null
`previous`	URL to the previous set of results (if any).	String or null	null
`results`	A list of group objects returned by the API.	Array of Objects	See below for details

Group Object Fields

Field Name	Description	Type	Example
`id`	Unique identifier for the group.	Integer	1
`name`	The name of the group.	String	“Administrators”
`users`	A list of user objects associated with the group. Each user object contains user information.	Array of Objects	See below for details
`description`	A description of the group. If not provided, this will be null.	String or null	“Default group for users with administrative access”
`permissions`	A list of permission IDs assigned to the group.	Array of Integers	[290, 291, 292, 293, …]
`object_permissions`	A list of object-level permissions (if any).	Array of Objects	[] (empty array)
`nas_group`	Information related to the group’s NAS configuration. If not applicable, this will be null.	Object or null	null or `{ "gid": 100000 }`

User Object Fields - For each user in the users array:

Field Name	Description	Type	Example
`username`	Username of the user.	String	“pixit”
`first_name`	The user’s first name.	String	“” (empty string)
`last_name`	The user’s last name.	String	“” (empty string)
`email`	The user’s email address.	String	“jenkins@example.com”
`date_joined`	The date when the user joined the system.	DateTime	“2025-05-14T12:06:59.927211Z”
`last_login`	The last time the user logged in.	DateTime or null	“2025-05-14T13:07:57.656518Z”

1.2.7.2. `POST` /groups/¶

Description

This API endpoint allows you to create a new group. By sending a POST request to this endpoint with the necessary details, a new group is created in the system. This includes specifying the group’s name, users, description, and permissions.

Request Parameters

Name	Description	Required
`name`	The name of the group being created (e.g., “Test Group”).	Yes
`users`	A list of user usernames to add to this group. For example: `["Test", "Example", "Example3"]`.	Yes
`description`	A brief description of the group (e.g., “A group for testing purposes”).	No
`permissions`	A list of permission IDs assigned to this group (e.g., `[305, 17, 109]`).	Yes

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/groups/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Test Group",
  "users": [
    "Test",
    "Example",
    "Example3"
  ],
  "description": "A group for testing purposes",
  "permissions": [
    305,
    17,
    109
  ]
}'

Successful Response

HTTP Status Code: 201 Created

Content-Type: application/json

The group has been successfully created.

Example Response

{
  "id": 5,
  "name": "Test Group",
  "users": [
    "Test",
    "Example",
    "Example3"
  ],
  "description": "A group for testing purposes"
  "permissions": [
    305,
    17,
    109
  ],
  "object_permissions": [],
  "nas_group": null
}

Response Fields

Name	Description
`id`	The unique identifier for the newly created group.
`name`	The name of the group (e.g., “Test Group”).
`users`	A list of usernames added to the group (e.g., `["Test", "Example", "Example3"]`).
`description`	The description of the group (e.g., “A group for testing purposes”).
`permissions`	A list of permission IDs associated with this group (e.g., `[305, 17, 109]`).
`object_permissions`	A list of object-level permissions. In this case, it is an empty list, meaning no object-level permissions are assigned.
`nas_group`	The NAS (Network Attached Storage) group associated with this group. In this case, it is `null` as no NAS group is provided.

1.2.7.3. `GET` /groups/{id}/¶

Description

This API endpoint retrieves detailed information about a specific group using its ID. It provides data such as:

The name of the group
A list of users assigned to the group (with user details like usernames, emails, join date, last login)
The permissions granted to the group
Any object permissions for the group
The description of the group (if available)

Request Parameters

Name	Description	Required	Type	Example
`id`	The unique identifier of the group you want to retrieve. This is a path parameter and should be included in the URL.	Yes	String	4

Example Request

curl -X GET 'http://your-hub-address:8000/api/groups/4/' \
-H 'accept: application/json' \
-H 'Authorization: Api-Key YOUR_API_KEY'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 4,
  "name": "API Test Group",
  "users": [
    {
      "username": "pixit",
      "first_name": "",
      "last_name": "",
      "email": "jenkins@example.com",
      "date_joined": "2025-05-14T12:06:59.927211Z",
      "last_login": "2025-05-14T13:07:57.656518Z"
    },
    {
      "username": "hubadmin",
      "first_name": "",
      "last_name": "",
      "email": "",
      "date_joined": "2025-05-23T10:57:26.219710Z",
      "last_login": "2025-07-04T14:17:23.449154Z"
    },
    {
      "username": "Test",
      "first_name": "Test",
      "last_name": "User",
      "email": "test@gmail.com",
      "date_joined": "2025-06-25T11:43:39.651419Z",
      "last_login": null
    },
    {
      "username": "Example",
      "first_name": "Example",
      "last_name": "User",
      "email": "user@gmail.com",
      "date_joined": "2025-06-25T11:53:37.572849Z",
      "last_login": null
    },
    {
      "username": "Example3",
      "first_name": "Example",
      "last_name": "User",
      "email": "",
      "date_joined": "2025-06-25T12:01:34.447630Z",
      "last_login": null
    }
  ],
  "description": "Group for API testing users",
  "permissions": [
    305,
    17,
    109,
    117,
    113
  ],
  "object_permissions": [],
  "nas_group": null
}

Response Fields

Refer to response fields under POST /Groups.

1.2.7.4. `PATCH` /groups/{id}/¶

Description

The PATCH /groups/{id}/ endpoint is used to update an existing group. You can modify the group’s name, users, permissions, and other attributes. This request is typically used to make partial updates to a group without changing the entire resource.

In this case, we are updating a group with the ID 5 by:

Modifying its name to "Test Group".
Adding/Removing users in the users array (in this case, users “Test” and “Example3”).
Modifying the permissions array (adding permission IDs 305, 17, and 109).

Request Parameters

Name	Description	Type	Required	Example
`id`	The unique identifier of the group that you want to update (path parameter). This is the ID of the group.	String	Yes	`5`
`data` (body)	An object containing the data to update the group with. The fields that can be included are: `name`, `users`, `permissions`.	Object	Yes	`{ "name": "Test Group", "users": ["Test", "Example3"], "permissions": [305, 17, 109] }`

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/groups/5/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Test Group",
  "users": [
    "Test",
    "Example3"
  ],
  "permissions": [
    305,
    17,
    109
  ]
}'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 5,
  "name": "Test Group",
  "users": [
    "Test",
    "Example3"
  ],
  "description": null,
  "permissions": [
    305,
    17,
    109
  ],
  "object_permissions": [],
  "nas_group": null
}

Response Fields

Field Name	Description	Type	Example
`id`	The unique identifier of the group.	Integer	`5`
`name`	The updated name of the group.	String	`"Test Group"`
`users`	A list of the usernames associated with this group.	Array of Strings	`["Test", "Example3"]`
`description`	The description of the group. If no description is provided, this will be `null`.	String or null	`null`
`permissions`	A list of permission IDs assigned to this group.	Array of Integers	`[305, 17, 109]`
`object_permissions`	A list of object-level permissions assigned to the group (if any).	Array of Objects	`[]` (empty array)
`nas_group`	Information about the group’s NAS configuration (if any). If not applicable, this will be `null`.	Object or null	`null`

1.2.7.5. `DELETE` /groups/{id}/¶

Description

This API endpoint is used to delete a specific group from the system based on its ID.

Request Parameters

Name	Description
`id` (path parameter)	The unique identifier of the group you wish to delete. It is provided in the URL path (e.g., `4`).

Example Request

curl -X 'DELETE' \
  'http://your-hub-address:8000/api/groups/4/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

No Request Body

Since this is a DELETE request, no body is required in the request. Only the ID is used to identify the group for deletion.

Successful Response

HTTP Status Code: 204 (No Content) – This status code indicates that the group was successfully deleted, and there is no additional content to return in the response body.

Content-Type: The response is in JSON format (application/json), but there is no body content as the request was successful (since it’s a DELETE operation).

1.2. API Endpoints - User and Access Management¶

1.2.1. Introduction¶

1.2.2. API Reference Location¶

1.2.3. Auth - Authentication¶

1.2.3.1. GET /auth/clientkeys/¶

1.2.3.2. GET /auth/clientkeys/{id}/¶

1.2.3.3. DELETE /auth/clientkeys/{id}/¶

1.2.3.4. GET /api/auth/token/publickey/¶

1.2.3.5. POST /api/auth/token/verify/¶

1.2.4. Users¶

1.2.4.1. GET /users/¶

1.2.4.2. POST /users/¶

1.2.4.3. POST /users/change_password/¶

1.2.4.4. GET /users/{username}/¶

1.2.4.5. PATCH /users/{username}/¶

1.2.4.6. DELETE /users/{username}/¶

1.2.4.7. POST /users/{username}/activate/¶

1.2.4.8. POST /users/{username}/deactivate/¶

1.2.5. My Permissions¶

1.2.5.1. GET /my-permissions/¶

1.2.6. Permissions¶

1.2.6.1. GET /permissions/¶

1.2.6.2. GET /permissions/{id}/¶

1.2.7. Groups¶

1.2.7.1. GET /groups/¶

1.2.7.2. POST /groups/¶

1.2.7.3. GET /groups/{id}/¶

1.2.7.4. PATCH /groups/{id}/¶

1.2.7.5. DELETE /groups/{id}/¶

1.2.3.1. `GET` /auth/clientkeys/¶

1.2.3.2. `GET` /auth/clientkeys/{id}/¶

1.2.3.3. `DELETE` /auth/clientkeys/{id}/¶

1.2.3.4. `GET` /api/auth/token/publickey/¶

1.2.3.5. `POST` /api/auth/token/verify/¶

1.2.4.1. `GET` /users/¶

1.2.4.2. `POST` /users/¶

1.2.4.3. `POST` /users/change_password/¶

1.2.4.5. `PATCH` /users/{username}/¶

1.2.4.6. `DELETE` /users/{username}/¶

1.2.4.7. `POST` /users/{username}/activate/¶

1.2.4.8. `POST` /users/{username}/deactivate/¶

1.2.6.1. `GET` /permissions/¶

1.2.6.2. `GET` /permissions/{id}/¶

1.2.7.1. `GET` /groups/¶

1.2.7.2. `POST` /groups/¶

1.2.7.3. `GET` /groups/{id}/¶

1.2.7.4. `PATCH` /groups/{id}/¶

1.2.7.5. `DELETE` /groups/{id}/¶