Skip to main content

REST API Overview

OrbisID exposes a RESTful API at /api/v1/ for all operations. The web UI uses this same API, so everything you can do in the browser can also be automated via the API.

Base URL​

https://your-orbisid-host/api/v1

All requests and responses use Content-Type: application/json.

Authentication​

The API supports two authentication methods.

Session Authentication​

Used by the web UI. Authenticate by calling the login endpoint:

curl -X POST https://your-orbisid-host/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

The response includes a session ID. Pass it on subsequent requests as either:

  • Cookie: ORBISID_SESSION=<session-id>
  • Header: X-Session-Id: <session-id>

API Key Authentication (Enterprise)​

For programmatic access, use an API key. Create one in Administration > API Keys, then pass it as a header:

curl https://your-orbisid-host/api/v1/dashboard/summary \
  -H "X-API-Key: your-api-key"

API keys provide the same access level as the Administrator role.

Pagination​

List endpoints support pagination with these query parameters:

ParameterDefaultDescription
page0Page number (zero-based)
size20Items per page (max 100)
sortvariesSort field and direction (e.g., createdAt,desc)

Paginated responses include:

{
  "content": [...],
  "totalElements": 150,
  "totalPages": 8,
  "size": 20,
  "number": 0
}

Error Responses​

All errors return a consistent JSON structure:

{
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed: name must not be blank",
  "timestamp": "2025-01-15T10:30:00Z"
}

HTTP Status Codes​

CodeMeaning
200Success
201Created
204No Content (successful deletion)
400Validation error
401Not authenticated
403Insufficient permissions or licence
404Resource not found
409Conflict (e.g., duplicate name)
500Internal server error

Interactive API Documentation​

OrbisID ships with a built-in Swagger UI served on a dedicated port (8443) so it can be kept separate from the main application — for example, blocked at the firewall in production or restricted to internal networks only.

ResourceURL
Swagger UIhttps://your-orbisid-host:8443/swagger-ui.html
OpenAPI JSONhttps://your-orbisid-host:8443/api-docs
OpenAPI YAMLhttps://your-orbisid-host:8443/api-docs.yaml

The Swagger UI lets you browse every endpoint, inspect request/response schemas, and execute requests directly from the browser.

Local development

When running the backend directly (without nginx), the docs are also available on the main port: http://localhost:8080/swagger-ui.html.

Endpoints Reference​

Authentication​

MethodEndpointDescription
POST/auth/loginAuthenticate and receive a session
POST/auth/logoutEnd current session
GET/auth/meGet current user details
POST/auth/change-passwordChange password
POST/auth/accept-eulaAccept end-user licence agreement

Dashboard​

MethodEndpointDescription
GET/dashboard/summarySystem, account, and identity statistics
GET/dashboard/krisCurrent KRI summary values
GET/dashboard/trendsKRI trend data for charts

Systems​

MethodEndpointDescription
GET/systemsList systems (paginated, filterable)
POST/systemsCreate a new system
GET/systems/{id}Get system details
PUT/systems/{id}Update a system
DELETE/systems/{id}Offboard a system
POST/systems/{id}/reonboardRe-onboard an offboarded system
POST/systems/test-connectionTest connection to a system
POST/systems/csv-importBulk import systems from CSV
GET/systems/csv-templateDownload CSV import template
POST/systems/ad-discoverDiscover systems via Active Directory
POST/systems/ad-test-connectionTest AD discovery connection
POST/systems/{id}/script-uploadUpload a custom scan script
GET/systems/{id}/script-versionsList custom script versions

Credentials​

MethodEndpointDescription
GET/credentialsList credentials
POST/credentialsCreate a credential
GET/credentials/{id}Get credential details
PUT/credentials/{id}Update a credential
DELETE/credentials/{id}Delete a credential
POST/credentials/{id}/pam-script-uploadUpload a PAM vault script
GET/credentials/{id}/pam-script-versionsList PAM script versions

Scan Policies​

MethodEndpointDescription
GET/scan-policiesList scan policies
POST/scan-policiesCreate a scan policy
GET/scan-policies/{id}Get policy details
PUT/scan-policies/{id}Update a policy
DELETE/scan-policies/{id}Delete a policy
POST/scan-policies/{id}/systemsAdd systems to a policy
DELETE/scan-policies/{id}/systems/{systemId}Remove a system from a policy

Scan Executions​

MethodEndpointDescription
POST/scans/triggerTrigger a scan (by policy or system)
GET/scans/{id}Get scan execution status
GET/scans/{id}/logsGet scan execution logs
GET/scans/{id}/systems-progressPer-system progress
POST/scans/{id}/stopStop a running scan
GET/scans/runningList currently running scans

Policy Rules​

MethodEndpointDescription
GET/policy-rulesList policy rules
POST/policy-rulesCreate a rule
GET/policy-rules/{id}Get rule details
PUT/policy-rules/{id}Update a rule
DELETE/policy-rules/{id}Delete a rule
POST/policy-rules/testTest a SpEL expression
GET/policy-rules/catalogueList rule templates

Accounts​

MethodEndpointDescription
GET/accountsList accounts (filterable by system, type, linked status)
GET/accounts/{id}Get account details
GET/accounts/{id}/detailsGet extended account details
GET/accounts/by-identity/{id}Get accounts linked to an identity
GET/accounts/statsAccount statistics
POST/accounts/{id}/link-identityLink an identity to an account
DELETE/accounts/{id}/link-identityUnlink an identity
POST/accounts/bulk-linkBulk link identities
POST/accounts/{id}/override-account-typeOverride account classification
DELETE/accounts/{id}/override-account-typeReset to rule-based classification

Identities​

MethodEndpointDescription
GET/identitiesList identities
POST/identitiesCreate an identity
GET/identities/{id}Get identity details
PUT/identities/{id}Update an identity
DELETE/identities/{id}Delete an identity

Entitlements​

MethodEndpointDescription
GET/entitlementsList entitlements
GET/entitlements/{id}Get entitlement details
GET/entitlements/statsEntitlement statistics
POST/entitlements/{id}/override-privilegeOverride privilege level
DELETE/entitlements/{id}/override-privilegeReset to rule-based
POST/entitlements/propagate-inheritancePropagate privilege inheritance

KRIs​

MethodEndpointDescription
GET/krisList current KRI values
GET/kris/definitionsList KRI definitions
PUT/kris/definitions/{code}Update a KRI definition
GET/kris/valuesGet current KRI values
GET/kris/trendsGet KRI trend data
POST/kris/snapshotsCreate a snapshot
GET/kris/snapshotsList snapshots
DELETE/kris/snapshots/{id}Delete a snapshot
GET/kris/exceptionsList KRI exceptions
POST/kris/exceptionsCreate an exception
PUT/kris/exceptions/{id}Update an exception
DELETE/kris/exceptions/{id}Delete an exception

Reports​

MethodEndpointDescription
GET/reports/typesList available report types
POST/reports/generateGenerate a report (query param: reportType)
POST/reports/generate/{type}Generate a report (path param)
POST/reports/exportExport report to CSV

PAM Accounts​

MethodEndpointDescription
GET/pam-accountsList PAM accounts
POST/pam-accountsCreate a PAM account
GET/pam-accounts/{id}Get PAM account details
PUT/pam-accounts/{id}Update a PAM account
DELETE/pam-accounts/{id}Delete a PAM account
POST/pam-accounts/csv-importBulk import from CSV
GET/pam-accounts/csv-templateDownload import template
GET/pam-accounts/statsPAM account statistics

PAM Reconciliation​

MethodEndpointDescription
GET/pam-reconciliationGet reconciliation results
POST/pam-reconciliation/runExecute reconciliation
POST/pam-reconciliation/{id}/linkLink account to PAM account
DELETE/pam-reconciliation/{id}/link/{pamId}Unlink
POST/pam-reconciliation/bulk-linkBulk link
GET/pam-reconciliation/statsReconciliation statistics

Users (Admin)​

MethodEndpointDescription
GET/usersList users
POST/usersCreate a user
GET/users/{id}Get user details
PUT/users/{id}Update a user
POST/users/{id}/activateActivate a user
POST/users/{id}/deactivateDeactivate a user
POST/users/{id}/reset-passwordReset password

API Keys (Admin, Enterprise)​

MethodEndpointDescription
GET/api-keysList API keys
POST/api-keysCreate an API key
POST/api-keys/{id}/enableEnable a key
POST/api-keys/{id}/disableDisable a key
DELETE/api-keys/{id}Delete a key

Audit Logs (Admin)​

MethodEndpointDescription
GET/audit-logsList audit logs (filterable)
GET/audit-logs/action-typesList available action types

Settings (Admin)​

MethodEndpointDescription
GET/settingsList all settings
GET/settings/mapGet settings as key-value map
GET/settings/{key}Get a single setting
PUT/settings/{key}Update a setting
PUT/settings/bulkBatch update settings

Password Policy (Admin)​

MethodEndpointDescription
GET/password-policyGet current policy
PUT/password-policyUpdate policy

OIDC (Admin, Enterprise)​

MethodEndpointDescription
GET/oidc/statusGet OIDC configuration status
GET/oidc/configGet OIDC configuration
PUT/oidc/configUpdate OIDC configuration
DELETE/oidc/configDelete OIDC configuration

Licence​

MethodEndpointDescription
GET/licenses/statusGet current licence status
GET/licenses/featuresGet available features and permissions
POST/licenses/activateActivate a licence key
POST/licenses/previewPreview a licence key before activating
POST/licenses/deactivateDeactivate the current licence

Version​

MethodEndpointDescription
GET/versionGet application version and build info