These endpoints manage tenant users and provide read access to roles, permissions, authentication settings, and API clients. POST /api/public/users is the only write endpoint in this article. Every other endpoint here is read-only. All endpoints are tenant-scoped: a request only returns users, roles, settings, and clients belonging to the tenant that issued the token.
List Users
Returns a paginated list of users in your tenant, ordered by creation date with the oldest user first.
Request
GET /api/public/users
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_Users_Read
Query Parameters
| Parameter | Type | Value |
|---|---|---|
limit | integer | Results per page. Default 50, maximum 200. |
cursor | string | Opaque page token. Omit on the first call. Pass nextCursor from the previous response on subsequent calls. |
updatedAfter | ISO 8601 timestamp | Resets the feed to the first page. Does not filter by date on this endpoint. Cannot be combined with cursor. |
Response Fields
| Field | Type | Value |
|---|---|---|
userId | integer | Unique identifier for the user. |
firstName | string | User's first name. |
lastName | string | User's last name. |
email | string | User's email address. |
state | string | Active, Invited, or Inactive. |
mfaStatus | boolean or null | Whether the user has enrolled in multi-factor authentication. null means unknown. |
mfaAction | boolean or null | Whether tenant policy enforces multi-factor authentication for this user. null means unknown. |
roleId | integer or null | Always null on this endpoint. Call GET /api/public/users/{id} for a user's roleId. |
roleName | string or null | The user's role name. |
createdAt | ISO 8601 timestamp | When the user was created. |
Sample Response
{
"data": [
{
"userId": 2141,
"firstName": "Ada",
"lastName": "Lovelace",
"email": "[email protected]",
"state": "Active",
"mfaStatus": true,
"mfaAction": true,
"roleId": null,
"roleName": "Tenant Admin",
"createdAt": "2025-11-03T14:22:00Z"
}
],
"pagination": {
"limit": 50,
"nextCursor": "eyJwYWdlTnVtYmVyIjoxfQ==",
"hasMore": true
},
"error": null,
"meta": {
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2026-08-13T10:00:00Z"
}
}
Users are ordered by creation date, oldest first, so a client that has caught up keeps its position and picks up new users on the next poll rather than seeing existing rows shift. A malformed or invalid cursor is rejected with a 400 error rather than falling back silently to the first page.
Error Responses
400 BAD_REQUEST:cursorandupdatedAfterwere supplied together.400 VALIDATION_FAILED: the cursor is malformed or invalid.401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_Users_Read. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error.
Get a User
Returns a single user by ID within your tenant.
Request
GET /api/public/users/{id}
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_Users_Read
{id} is the userId returned by GET /api/public/users. Not paginated; pagination is null. The response fields are the same as the list endpoint, with roleId populated.
Sample Response
{
"data": {
"userId": 2141,
"firstName": "Ada",
"lastName": "Lovelace",
"email": "[email protected]",
"state": "Active",
"mfaStatus": true,
"mfaAction": true,
"roleId": 12,
"roleName": "Tenant Admin",
"createdAt": "2025-11-03T14:22:00Z"
},
"pagination": null,
"error": null,
"meta": {
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2026-08-13T10:05:00Z"
}
}
This is the only way to retrieve a user's roleId through the Public API; the list endpoint always returns null for this field. A user belonging to more than one tenant has a role per tenant, and only the calling tenant's role is returned.
Error Responses
404 NOT_FOUND: the user does not exist, or belongs to a different tenant. The two cases are indistinguishable by design.403 Forbidden(malformed ID): the ID in the path is malformed. The response gives the detail "This endpoint does not permit the request." and has norequiredPermission. A malformed ID returns 403, not 404.401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_Users_Read. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error.
Create a User
Creates a user in your tenant with exactly one role assigned.
Request
POST /api/public/users
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_Users_Create. This is a separate permission from Api_Users_Read; a read-only client cannot create users.
Request Body: All Fields Required
| Field | Type | Rules |
|---|---|---|
firstName | string | 1-255 characters. |
lastName | string | 1-255 characters. |
email | string | 1-255 characters. Must be a valid email address. |
roleId | integer | Must be greater than 0 and must match a role in your tenant. Discover valid values with GET /api/public/roles. |
Sample Request
{
"firstName": "Grace",
"lastName": "Hopper",
"email": "[email protected]",
"roleId": 12
}
Sample Response (201 Created)
{
"data": {
"userId": 2288,
"firstName": "Grace",
"lastName": "Hopper",
"email": "[email protected]",
"state": "Invited",
"mfaStatus": false,
"mfaAction": true,
"roleId": 12,
"roleName": "Security Analyst",
"createdAt": "2026-08-13T10:10:00Z"
},
"pagination": null,
"error": null,
"meta": {
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2026-08-13T10:10:00Z"
}
}
The new user is created in an Invited state. An invitation is sent, and the account activates once the user completes enrollment. This endpoint is not idempotent and has no request-deduplication key: if a request times out and you retry it, a 409 CONFLICT response may mean the first attempt actually succeeded. Treat it as "already created" rather than a failure.
Error Responses
409 CONFLICT: a user with this email address already exists in your tenant.422 VALIDATION_FAILED: a field is missing, out of length, not a valid email, orroleIdis missing, not greater than 0, or does not match a role in your tenant.401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_Users_Create. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error.
List Roles
Returns every role in your tenant, along with each role's assigned permissions.
Request
GET /api/public/roles
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_Roles_Read
Not paginated. pagination is null; the full list is returned in data.
Response Fields
| Field | Type | Rules |
|---|---|---|
roleId | integer | Unique identifier for the role. |
name | string | Role name. |
description | string | Role description. |
state | integer | Active or Inactive. Inactive roles are included in the response. |
type | integer | User for roles assignable to people (what POST /api/public/users expects), or Api for roles attached to API clients. |
isReadOnly | boolean | Whether this is a built-in role that cannot be modified. |
permissions | array | The permissions assigned to this role, in the same shape as GET /api/public/permissions. |
Sample Response
{
"data": [
{
"roleId": 12,
"name": "Tenant Admin",
"description": "Full administrative access within the tenant",
"state": "Active",
"type": "User",
"isReadOnly": true,
"permissions": [
{
"permissionId": 269,
"name": "Read",
"module": "API",
"function": "Users",
"code": "Api_Users_Read"
}
]
}
],
"pagination": null,
"error": null,
"meta": {
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2026-08-13T10:15:00Z"
}
}
Only roles with type: "User" are valid for the roleId field on POST /api/public/users. Inactive roles are returned; filter on state if you only want assignable roles. No ordering is guaranteed, so sort client-side if you need a stable order.
Error Responses
401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_Roles_Read. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error, including an upstream failure. This endpoint returns an error rather than an empty list when role data cannot be retrieved, so an emptydataarray always means your tenant genuinely has no roles.
Get a Role
Returns a single role by ID, scoped to your tenant.
Request
GET /api/public/roles/{id}
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_Roles_Read
{id} is the roleId returned by GET /api/public/roles. Not paginated. The response is the same shape as the list endpoint. If you need several roles, prefer one call to GET /api/public/roles over multiple calls to this endpoint.
Error Responses
404 NOT_FOUND: the role does not exist, or belongs to a different tenant.403 Forbidden(malformed ID): the ID in the path is malformed. The response gives the detail "This endpoint does not permit the request." and has norequiredPermission. A malformed ID returns 403, not 404.401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_Roles_Read. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error.
List Permissions
Returns the catalog of permissions that can be assigned to roles.
Request
GET /api/public/permissions
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_Roles_Read
Not paginated.
Response Fields
| Field | Type | Rules |
|---|---|---|
permissionId | integer | Unique identifier for the permission. |
name | string | Action name, e.g. Read or Create. |
module | string | Grouping, e.g. API. |
function | integer | The area the permission applies to, e.g. Users. |
code | integer | The stable identifier for the permission, e.g. Api_Users_Read. Use this to reference a permission; do not reconstruct it from module, function, and name. |
Sample Response
{
"data": [
{
"permissionId": 269,
"name": "Read",
"module": "API",
"function": "Users",
"code": "Api_Users_Read"
}
],
"pagination": null,
"error": null,
"meta": {
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2026-08-13T10:25:00Z"
}
}
This catalog may include permissions that do not yet gate any endpoint. Ordering is not guaranteed; sort client-side if you need a stable order.
The catalog includes Api_Vulnerabilities_Update, which lets an API client set a vulnerability's status. It is not on the Default API Role. To use it, an administrator creates an API role that includes it and assigns that role to the API client.
Error Responses
401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_Roles_Read. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error, including an upstream failure. As with roles, an emptydataarray always means your tenant genuinely has no assignable permissions.
Get Authentication Settings
Returns your tenant's authentication configuration: SSO settings and multi-factor authentication policy.
Request
GET /api/public/authentication-settings
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_AuthSettings_Read
Not paginated. data is a single object.
Response Fields
| Field | Type | Rules |
|---|---|---|
ssoEnabled | boolean | Whether SSO is configured for the tenant. |
ssoEnforced | boolean | Whether users must authenticate via SSO. Check this together with ssoEnabled: SSO can be enabled but optional. |
providerType | string or null | The identity provider, e.g. AzureAD. null when SSO is not configured. |
tenantName | string or null | The tenant identifier registered with the SSO provider. null when SSO is not configured. |
mfaEnabled | boolean | The tenant-wide multi-factor authentication policy. Corresponds to mfaAction on users records. |
Sample Response: SSO Configured
{
"data": {
"ssoEnabled": true,
"ssoEnforced": false,
"providerType": "AzureAD",
"tenantName": "contoso",
"mfaEnabled": true
},
"pagination": null,
"error": null,
"meta": {
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2026-08-13T10:30:00Z"
}
}
Sample Response: No SSO Configured
{
"data": {
"ssoEnabled": false,
"ssoEnforced": false,
"providerType": null,
"tenantName": null,
"mfaEnabled": false
},
"pagination": null,
"error": null,
"meta": {
"requestId": "7b8c9d0e-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
"timestamp": "2026-08-13T10:30:01Z"
}
}
A tenant without SSO configured returns 200 with these defaults, not an error. mfaEnabled is the tenant-wide policy, not a per-user state; combine it with GET /api/public/users to find users who have not yet enrolled under an enforcing policy.
Error Responses
401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_AuthSettings_Read. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error.
List API Clients
Returns metadata for the API clients registered in your tenant, including the client you are using to make this request.
Request
GET /api/public/api-clients
Authentication
Bearer token. See Authentication & Generating Credentials.
Required Permission
Api_ApiClients_Read
Query Parameters
| Parameter | Type | Value |
|---|---|---|
pageSize | integer | Results per page. Default 50, maximum 200. This endpoint uses pageSize, not limit. |
cursor | string | Opaque page token from the previous response. Omit on the first call |
Response Fields
| Field | Type | Rules |
|---|---|---|
clientId | string | Public identifier for the client. Not a credential; safe to log. |
name | string | Client name. |
roleName | string | The API role attached to this client. null means no role is attached. The client can authenticate, but every endpoint refuses it with 403 Forbidden. |
secretExpirationDate | integer | When the client's secret expires. |
createdAt | integer | When the client was created. |
Sample Response
{
"data": [
{
"clientId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "ServiceNow connector",
"roleName": "Default API Role",
"secretExpirationDate": "2027-07-17T00:00:00Z",
"createdAt": "2026-07-17T10:00:00Z"
}
],
"pagination": {
"nextCursor": "cDox",
"hasMore": true
},
"error": null,
"meta": {
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2026-08-13T10:35:00Z"
}
}
Client secrets are never returned by this or any endpoint; a secret is shown once, at create, in the portal. secretExpirationDate is the main reason to poll this endpoint. Alert ahead of expiry so a client's secret doesn't lapse without warning. A malformed or invalid cursor is ignored and the first page is returned, rather than rejected, which differs from GET /api/public/users. An empty data array with hasMore: false can mean either that your tenant has no API clients or that the request could not be completed; re-poll to confirm before treating an empty result as authoritative.
Error Responses
401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_ApiClients_Read. The response names the missing permission inrequiredPermission. Grant that permission to the API client's role. Do not refresh the token.503 Service Unavailable: permissions could not be verified. Retry the request after a short wait.500 INTERNAL_ERROR: an unexpected server error.





