XTHREATSECURE / POSTURE API

Connected security.
Clearer decisions.

Connect organisational context, security findings and assurance evidence to your reporting workflows.

Start integrating →Explore endpoints

BASE PATH/api/v1

DATA FORMATJSON

API VERSION1.0

SPECIFICATIONOpenAPI 3.1

01 / GETTING STARTED

Your first request

Use the base URL supplied for your environment. Start with a read request to check connectivity, then retrieve the organisation and its departments.

Check connectivity

GET /health returns service status and the current workspace revision.

Explore your reporting scope

Retrieve /organisation and /departments, then use department identifiers to filter findings, assets and source records.

Connect a workflow

Use a documented command to update remediation, submit evidence or configure collection. Include the latest workspace revision.

Example request · cURL

Replace the base URL when using another environment.

AUTHENTICATION

Connect securely

Browser users sign in with a username and password. Customer services authenticate with their own client ID and secret, without using a person's password.

1. Register an integration

An administrator creates a client in Customer API clients, choosing its scopes and departments. Save the secret when shown; it cannot be retrieved later.

2. Request an access token

Send grant_type=client_credentials to /oauth/token, authenticating with HTTP Basic using the client ID and secret. The access token lasts 3,600 seconds. Request another token when it expires; no refresh token is issued.

3. Call the API

Include Authorization: Bearer <access_token>. Tokens are opaque: do not parse them or put them in URLs. A client cannot access departments outside its grant or increase access using reporting-context fields.

Client credentials · cURL

Use environment variables or a secret manager; never embed client secrets in a browser application.

Scope	Access
`posture:read`	Authorised records, analytics and reports. Administrator workspace resources require a browser session.
`posture:write`	Remediation updates, source sync and collection-schedule configuration within granted departments. Other workflows require an interactive session.

Browser sessions last eight hours and use an HttpOnly, SameSite cookie. Session-based mutations require the CSRF token returned by /auth/session. Signing out invalidates the session. Revoking a customer client invalidates all its access tokens immediately. This implementation supports the client credentials grant; interactive SSO and delegated authorisation-code grants are not implemented.

02 / API CONVENTIONS

Predictable requests and responses

↳

Scope and pagination

Filter collection requests by department_id and reporting period. Use offset and limit to page through results; the maximum page size is 500.

↻

Safe workflow updates

Commands require revision, context and the documented args. A stale revision returns 409 without applying the change.

◎

Traceable evidence

Records retain identifiers, source context and reporting timestamps. Missing evidence remains distinct from a zero value or low risk.

03 / ENDPOINT REFERENCE

Find the right endpoint

Browse by capability. Expand an endpoint for parameters, request examples and response details.

04 / ERROR HANDLING

Resolve a rejected request

Error responses use application/problem+json with status, title and detail.

Status	Meaning	Next step
`401`	Authentication required or expired	Sign in again or request a new access token.
`400`	Invalid request or workflow state	Check the response detail, field types and transition requirements.
`403`	Access or request origin rejected	Check token scopes, department grants and the CSRF header for browser writes.
`404`	Route or record unavailable	Check the identifier and selected reporting scope.
`409`	Workspace revision has changed	Retrieve the latest revision and review your change before retrying.
`413 / 415`	Payload too large or unsupported format	Keep requests below 2 MB and use `application/json`.