Skip to content

SenseOn Connect API Reference

SenseOn Connect is a bidirectional API. It lets you interact programmatically with most data in the SenseOn platform.

API Capabilities

The API supports these functions:

  • Read security cases: Retrieve details of security cases.
  • Update security cases: Include comments and update the status.
  • Read device information: Access information on all registered devices.
  • Read all security observations: Access detailed observations related to security incidents.
  • Read all raw telemetry: Get raw telemetry data for deeper analysis.
  • Write security observations: You must get approval from SenseOn for this feature.
  • AI case summaries: Access and generate AI-powered case summaries through the API.
  • Read and update appliance settings: Read tenant settings by name or wildcard pattern, and update them programmatically.
  • Read environment context: Retrieve the customer-authored environment context, with the built-in sections and any custom blocks.

The API serves all endpoints under https://<your-tenant>.senseon.io/api. For example, a GET /v1/settings request goes to https://<your-tenant>.senseon.io/api/v1/settings. To authenticate, send your token in the Authorization: Bearer <token> header.

Token Scopes

When you create a token, you grant it one or more scopes:

cases/read, cases/write, devices/read, observations/read, observations/write, telemetry/read, settings/read, settings/write

Rate Limiting

Each endpoint is in one of three tiers of rate limits. The low tier is ~10 requests per minute. The medium tier is ~60 requests per minute. The high tier is ~600 requests per minute. If you exceed the limit of a tier, the API returns 429 Too Many Requests.

Create an API Token

To interact with SenseOn Connect on your platform, you must create an access token. Go to Settings > Integrations > API Configuration.

This page shows all the tokens that were created. The list also shows the deleted tokens. For each token, the page shows who created it, its permissions, its status, and when it was last used.

API Settings

To create a new token, click the Create token button. A popup then guides you through the process.

Create API token

After the popup shows the token, you cannot get access to the token again. If you lose the token, you must create a new token.

API new key popup

Test the API

Next, you can open the live documentation and test the API token with real data on your system. Click Read the documentation.

API Reference

HTTP basic auth protects the documentation. To open the documentation, enter any username. Use the API token that you generated as the password.

To authorise your API key with the documentation website, click Authorise.

API Authorisation Process

Then enter your token in the Personal Access Token field. Select Authorise.

API Authorisation Popup

You can examine each API feature in detail. To send real queries to the API and get real responses, click Try it out. Then click Execute. The page also gives a cURL output, which makes integration with other tools easier.

API Test Pages

AI Case Summaries

You can use the SenseOn Connect API to access and manage AI case summaries:

  • POST /v1/cases - Includes any AI summaries that were already generated on cases
  • POST /v1/cases/{case_id}/summary - Generates (or generates again) a new LLM summary for a specific case
  • GET /v1/cases/{case_id} - Retrieves case details with summaries, but only if the summaries were already generated

For more information about AI case summaries, refer to the AI Generated Case Summaries documentation.

Settings API

You can read and update appliance settings programmatically. To read settings, a token must have the settings/read scope. To update settings, a token must have the settings/write scope. A token can access only the settings that the user who created it has permission to see.

Method Path Description
GET /v1/settings?names=... Read one or more settings. Each name can be exact (senseon.llm.enabled) or a trailing-wildcard pattern (notifications.*). If the token does not have permission to read a setting, the response gives that setting with an error of NOT_AUTHORIZED. Unknown names return NOT_FOUND.
PUT /v1/settings Update one or more settings. The body maps setting names to new values. Updates are all-or-nothing. If a setting is unknown, not permitted, or does not pass validation, the API returns a 400. This response maps the names that caused the error to error messages.

Example read:

curl -H "Authorization: Bearer <token>" \
  "https://<your-tenant>.senseon.io/api/v1/settings?names=notifications.*"

Each setting in the response includes its name, current value, kind, friendly_name, and description. It also shows whether your token has update_permission.

Environment Context API

You can read the customer-authored Environment context programmatically. For this endpoint, a token must have the settings/read scope.

Method Path Description
GET /v1/environment_context Read the environment context: the built-in sections, your custom blocks, and when and by whom it was last saved. If nothing is saved on an appliance, the appliance returns an empty record.

The response contains:

  • sections: the three built-in sections (accounts, network_locations and known_environment). Each section is a plain-text string.
  • blocks: your custom blocks in display order, each with a title, content and a list of keywords.
  • updated_at: the last-saved time in milliseconds since the Unix epoch, or null if the context was never saved.
  • updated_by: the email of the user who last saved it, or null if the user is not known.

Example read:

curl -H "Authorization: Bearer <token>" \
  "https://<your-tenant>.senseon.io/api/v1/environment_context"

Personal Access Token API Endpoints

You can use the Customer Accessible API (CAA) to manage Personal Access Tokens (PATs) programmatically. For information about how to create and scope tokens in the UI, refer to Personal Access Tokens.

⚠ Availability: If a path in the table that follows returns 404, use the UI to manage tokens. SenseOn releases the PAT management endpoints with appliance updates. Thus, it is possible that your tenant does not support them yet. You can always manage tokens in the UI at Settings > Integrations > API Configuration.

Endpoints

Method Path Description
GET /senseonapi/caa/pats/scopes Return the scopes assigned to the token that authenticates the request (you must send the request with that token)
POST /senseonapi/caa/pats Create a new Personal Access Token
GET /senseonapi/caa/pats List the tokens that the authenticated user owns
GET /senseonapi/caa/pats/all List tokens for all users (the ui/caa_pat/admin permission is necessary)
DELETE /senseonapi/caa/pats/{pat_id} Revoke a token by its ID (returns HTTP 204 on success)

Create token request body

{
  "name": "my-integration",
  "expiry_at": 1798761599000,
  "scopes": ["cases/read", "devices/read"]
}

expiry_at is a timestamp in milliseconds since the Unix epoch. It is not an ISO 8601 string. The timestamp in the example is 2026-12-31T23:59:59Z. This timestamp must be in the future.

The response includes the pat_id (UUID) and the token value. The API returns the token value only once. You cannot retrieve it again.

Service Account API Endpoints

Service accounts are non-human identities. Each service account uses a single token to authenticate to the Customer Accessible API. For information about how to create and manage service accounts in the UI, refer to Service Accounts.

The ui/service_accounts/manage permission is necessary for all service account endpoints. The Admin role has this permission.

⚠ Availability: If a path in the table that follows returns 404, use the UI to manage service accounts. SenseOn releases the service account endpoints with appliance updates. Thus, it is possible that your tenant does not support them yet. You can always manage service accounts in the UI at Settings > Service Accounts.

Endpoints

Method Path Description
GET /senseonapi/service_accounts List all service accounts
POST /senseonapi/service_accounts Create a service account
GET /senseonapi/service_accounts/{user_id} Retrieve a single service account
PATCH /senseonapi/service_accounts/{user_id} Update a service account (only the fields that you supply change)
DELETE /senseonapi/service_accounts/{user_id} Delete a service account and revoke its token (returns HTTP 204 on success)
POST /senseonapi/service_accounts/{user_id}/token Issue the token of the account, and revoke the token that the account already has
DELETE /senseonapi/service_accounts/{user_id}/token Revoke the active token of the account (returns HTTP 204 on success)

Create service account request body

{
  "name": "SOC Automation",
  "description": "Automated case triage"
}

The name must be unique across service accounts. When you create the account, the API derives an email that identifies the account from the name. This email does not change if you rename the account later.

Update service account request body

Only the fields that you supply change. Do not send a field as null. To keep a field unchanged, do not include it in the request.

{
  "name": "SOC Automation",
  "description": "Automated case triage and export",
  "enabled": false
}

Issue token request body

{
  "scopes": ["cases/read", "cases/write"],
  "expiry_at": 1798761599000
}

expiry_at is a timestamp in milliseconds since the Unix epoch, or null for a token that never expires. The response includes the pat_id, scopes, expiry_at, and the token value. As with a personal access token, the API returns the value only once. If the account is disabled, the API returns a 409 Conflict.


HTTP Status Codes

The API uses standard HTTP status codes. The table that follows gives the codes that are specific to SenseOn behaviour:

Code Meaning
200 OK Request succeeded
201 Created Resource created successfully
202 Accepted Asynchronous operation accepted (for example, a Hunt Lab query is in the queue)
204 No Content Successful deletion (for example, a PAT was revoked)
400 Bad Request Invalid input: look for a VALIDATION_ERROR detail in the response body
401 Unauthorized Not authenticated: make sure that your token is correct, or log in again
403 Forbidden Authenticated but not authorised for this action
404 Not Found The requested resource does not exist
428 Precondition Required Step-up authentication is necessary before this action can continue: authenticate again and try again
500 Internal Server Error Unexpected server error: if the error continues, contact support
503 Service Unavailable The service is temporarily not available
504 Gateway Timeout A database query timed out: try a more specific query, or try again later

Error Codes

Error responses include a machine-readable code field in the JSON body:

Code Description
VALIDATION_ERROR One or more request fields did not pass validation
INTERNAL_SERVER_ERROR An unexpected error occurred on the server
INVALID_PAT_ID The specified Personal Access Token ID does not exist or does not belong to the authenticated user
INVALID_ENDPOINT_ID One or more endpoint IDs in the request are invalid
INVALID_SCRIPT_ID The specified script ID does not exist
INVALID_ACTION_ID The specified action ID does not exist
INVALID_CASE_ID The specified case ID does not exist
INVALID_DEVICES One or more devices are not eligible for the requested action (for example, wrong OS or unsupported agent version)
INVALID_SCRIPT_INPUT One or more script parameters did not pass validation
FORBIDDEN The authenticated user does not have permission for this action

Rate Limiting

Some endpoints enforce rate limits to protect the stability of the platform:

Endpoint Limit
GET /senseonapi/users/resend-invite 1 request per 30 seconds per user
POST /senseonapi/users/current/totp 4 requests per second; 5 requests per 60 seconds

If a request exceeds these limits, it gets a 429 Too Many Requests response. Wait until the limit window ends before you try again.


Creating Observations

You can use the API to create observations, but SenseOn must approve this action first. The review process examines:

  • The impact on any managed services.
  • How the data will correlate with other observations.
  • The expected volume of observations.

To start this review process, contact the SenseOn support team.