Find the insights and best practices about our product.
Users, Roles & Access Management

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

ParameterTypeValue
limitintegerResults per page. Default 50, maximum 200.
cursorstringOpaque page token. Omit on the first call. Pass nextCursor from the previous response on subsequent calls.
updatedAfterISO 8601 timestampResets the feed to the first page. Does not filter by date on this endpoint. Cannot be combined with cursor.

Response Fields

FieldTypeValue
userIdintegerUnique identifier for the user.
firstNamestringUser's first name.
lastNamestringUser's last name.
emailstringUser's email address.
statestringActive, Invited, or Inactive.
mfaStatusboolean or nullWhether the user has enrolled in multi-factor authentication. null means unknown.
mfaActionboolean or nullWhether tenant policy enforces multi-factor authentication for this user. null means unknown.
roleIdinteger or nullAlways null on this endpoint. Call GET /api/public/users/{id} for a user's roleId.
roleNamestring or nullThe user's role name.
createdAtISO 8601 timestampWhen 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: cursor and updatedAfter were 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 include Api_Users_Read. The response names the missing permission in requiredPermission. 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 no requiredPermission. 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 include Api_Users_Read. The response names the missing permission in requiredPermission. 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

FieldTypeRules
firstNamestring1-255 characters.
lastNamestring1-255 characters.
emailstring1-255 characters. Must be a valid email address.
roleIdintegerMust 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, or roleId is 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 include Api_Users_Create. The response names the missing permission in requiredPermission. 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

FieldTypeRules
roleIdintegerUnique identifier for the role.
namestringRole name.
descriptionstringRole description.
stateintegerActive or Inactive. Inactive roles are included in the response.
typeintegerUser for roles assignable to people (what POST /api/public/users expects), or Api for roles attached to API clients.
isReadOnlybooleanWhether this is a built-in role that cannot be modified.
permissionsarrayThe 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 include Api_Roles_Read. The response names the missing permission in requiredPermission. 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 empty data array 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 no requiredPermission. 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 include Api_Roles_Read. The response names the missing permission in requiredPermission. 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

FieldTypeRules
permissionIdintegerUnique identifier for the permission.
namestringAction name, e.g. Read or Create.
modulestringGrouping, e.g. API.
functionintegerThe area the permission applies to, e.g. Users.
codeintegerThe 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 include Api_Roles_Read. The response names the missing permission in requiredPermission. 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 empty data array 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

FieldTypeRules
ssoEnabledbooleanWhether SSO is configured for the tenant.
ssoEnforcedbooleanWhether users must authenticate via SSO. Check this together with ssoEnabled: SSO can be enabled but optional.
providerTypestring or nullThe identity provider, e.g. AzureAD. null when SSO is not configured.
tenantNamestring or nullThe tenant identifier registered with the SSO provider. null when SSO is not configured.
mfaEnabledbooleanThe 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 include Api_AuthSettings_Read. The response names the missing permission in requiredPermission. 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

ParameterTypeValue
pageSizeintegerResults per page. Default 50, maximum 200. This endpoint uses pageSize, not limit.
cursorstringOpaque page token from the previous response. Omit on the first call

Response Fields

FieldTypeRules
clientIdstringPublic identifier for the client. Not a credential; safe to log.
namestringClient name.
roleNamestringThe API role attached to this client. null means no role is attached. The client can authenticate, but every endpoint refuses it with 403 Forbidden.
secretExpirationDateintegerWhen the client's secret expires.
createdAtintegerWhen 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 include Api_ApiClients_Read. The response names the missing permission in requiredPermission. 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.
Did this answer your question?