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://orbisid.example.local/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://orbisid.example.local/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "your-password"}'
curl -X POST https://orbisid.example.local/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "your-password"}'
Invoke-RestMethod -Uri https://orbisid.example.local/api/v1/auth/login `
-Method Post `
-Body (@{ username = "admin"; password = "your-password" } | ConvertTo-Json) `
-ContentType "application/json"
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)
Requires Enterprise edition — not available on Community.
For programmatic access, use an API key. Create one in Administration > Access & Security > API Keys, then pass it as a header:
curl https://orbisid.example.local/api/v1/dashboard/summary \
-H "X-API-Key: your-api-key"
curl https://orbisid.example.local/api/v1/dashboard/summary \
-H "X-API-Key: your-api-key"
Invoke-RestMethod -Uri https://orbisid.example.local/api/v1/dashboard/summary `
-Headers @{ "X-API-Key" = "your-api-key" }
API keys provide the same access level as the Administrator role.
List endpoints support pagination with these query parameters:
| Parameter | Default | Description |
|---|
page | 0 | Page number (zero-based) |
size | 20 | Items per page (max 100) |
sort | varies | Sort 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
| Code | Meaning |
|---|
| 200 | Success |
| 201 | Created |
| 204 | No Content (successful deletion) |
| 400 | Validation error |
| 401 | Not authenticated |
| 403 | Insufficient permissions or licence |
| 404 | Resource not found |
| 409 | Conflict (e.g., duplicate name) |
| 429 | Too many requests: SDK API rate limit exceeded (see Rate Limits) |
| 500 | Internal 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.
| Resource | URL |
|---|
| Swagger UI | https://orbisid.example.local:8443/swagger-ui.html |
| OpenAPI JSON | https://orbisid.example.local:8443/api-docs |
| OpenAPI YAML | https://orbisid.example.local:8443/api-docs.yaml |
The Swagger UI lets you browse every endpoint, inspect request/response schemas, and execute requests directly from the browser.
The API reference is available to administrators only. Sign in to OrbisID in the same browser first (the session cookie is shared across ports on the same host), or open the Swagger UI and use Authorize to enter a session ID for the sessionId scheme. SDK endpoints use the apiKey scheme (X-API-Key).
When running the backend directly (without nginx), the docs are also available on the main port: http://localhost:8080/swagger-ui.html.
Rate Limits
The SDK API (/api/v1/sdk/*) is rate limited. Two limits apply, and a request must be within both:
| Limit | Default | Applies to |
|---|
| Per API key | 120 requests per minute | All callers using the same API key |
| Per client IP address | 300 requests per minute | Every SDK request from that address, including requests with a missing or incorrect key |
A request over a limit receives 429 Too Many Requests with a Retry-After header giving the number of seconds to wait:
HTTP/1.1 429 Too Many Requests
Retry-After: 20
Content-Type: application/json
{"error": "Too Many Requests", "message": "Rate limit exceeded. Retry after 20 seconds."}
Allowance is replenished continuously, so a client can send a burst up to its per-minute limit and is then held to the average rate. Well-behaved clients should wait for Retry-After before retrying.
Administrators can change the limits, or turn limiting off, with these settings (PUT /api/v1/settings):
| Setting | Default | Description |
|---|
sdk.rate_limit.enabled | true | Turn SDK rate limiting on or off |
sdk.rate_limit.per_key_per_minute | 120 | Requests per minute for one API key |
sdk.rate_limit.per_ip_per_minute | 300 | Requests per minute from one IP address |
Changes take effect within about 30 seconds. Counters are held in memory on each backend instance and reset when it restarts. Behind a reverse proxy, the client address is taken from the proxy's X-Forwarded-For header, so make sure your proxy sets it.
Endpoints Reference
Authentication
| Method | Endpoint | Description |
|---|
POST | /auth/login | Authenticate and receive a session |
POST | /auth/logout | End current session |
GET | /auth/me | Get current user details |
POST | /auth/change-password | Change password |
POST | /auth/accept-eula | Accept end-user licence agreement |
Dashboard
| Method | Endpoint | Description |
|---|
GET | /dashboard/summary | System, account, and identity statistics |
GET | /dashboard/kris | Current KRI summary values |
GET | /dashboard/trends | KRI trend data for charts |
Systems
| Method | Endpoint | Description |
|---|
GET | /systems | List systems (paginated, filterable) |
POST | /systems | Create a new system |
GET | /systems/{id} | Get system details |
PUT | /systems/{id} | Update a system |
DELETE | /systems/{id} | Offboard a system |
POST | /systems/{id}/reonboard | Re-onboard an offboarded system |
POST | /systems/test-connection | Test connection to a system |
POST | /systems/csv-import | Bulk import systems from CSV |
GET | /systems/csv-template | Download CSV import template |
POST | /systems/ad-discover | Discover systems via Active Directory |
POST | /systems/ad-test-connection | Test AD discovery connection |
POST | /systems/{id}/script-upload | Upload a custom scan script |
GET | /systems/{id}/script-versions | List custom script versions |
Credentials
| Method | Endpoint | Description |
|---|
GET | /credentials | List credentials |
POST | /credentials | Create 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-upload | Upload a PAM vault script |
GET | /credentials/{id}/pam-script-versions | List PAM script versions |
Scan Policies
| Method | Endpoint | Description |
|---|
GET | /scan-policies | List scan policies |
POST | /scan-policies | Create 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}/systems | Add systems to a policy |
DELETE | /scan-policies/{id}/systems/{systemId} | Remove a system from a policy |
Scan Executions
| Method | Endpoint | Description |
|---|
POST | /scans/trigger | Trigger a scan (by policy or system) |
GET | /scans/{id} | Get scan execution status |
GET | /scans/{id}/logs | Get scan execution logs |
GET | /scans/{id}/systems-progress | Per-system progress |
POST | /scans/{id}/stop | Stop a running scan |
GET | /scans/running | List currently running scans |
Classification Rules
| Method | Endpoint | Description |
|---|
GET | /policy-rules | List policy rules |
POST | /policy-rules | Create 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/test | Test a SpEL expression |
GET | /policy-rules/catalogue | List rule templates |
Accounts
| Method | Endpoint | Description |
|---|
GET | /accounts | List accounts (filterable by system, type, linked status) |
GET | /accounts/{id} | Get account details |
GET | /accounts/{id}/details | Get extended account details |
GET | /accounts/by-identity/{id} | Get accounts linked to an identity |
GET | /accounts/stats | Account statistics |
POST | /accounts/{id}/link-identity | Link an identity to an account |
DELETE | /accounts/{id}/link-identity | Unlink an identity |
POST | /accounts/bulk-link | Bulk link identities |
POST | /accounts/{id}/override-account-type | Override account classification |
DELETE | /accounts/{id}/override-account-type | Reset to rule-based classification |
Identities
| Method | Endpoint | Description |
|---|
GET | /identities | List identities |
POST | /identities | Create an identity |
GET | /identities/{id} | Get identity details |
PUT | /identities/{id} | Update an identity |
DELETE | /identities/{id} | Delete an identity |
Entitlements
| Method | Endpoint | Description |
|---|
GET | /entitlements | List entitlements |
GET | /entitlements/{id} | Get entitlement details |
GET | /entitlements/stats | Entitlement statistics |
POST | /entitlements/{id}/override-privilege | Override privilege level |
DELETE | /entitlements/{id}/override-privilege | Reset to rule-based |
POST | /entitlements/propagate-inheritance | Propagate privilege inheritance |
KRIs
| Method | Endpoint | Description |
|---|
GET | /kris | List current KRI values |
GET | /kris/definitions | List KRI definitions |
PUT | /kris/definitions/{code} | Update a KRI definition |
GET | /kris/values | Get current KRI values |
GET | /kris/trends | Get KRI trend data |
POST | /kris/snapshots | Create a snapshot |
GET | /kris/snapshots | List snapshots |
DELETE | /kris/snapshots/{id} | Delete a snapshot |
GET | /kris/exceptions | List KRI exceptions |
POST | /kris/exceptions | Create an exception |
PUT | /kris/exceptions/{id} | Update an exception |
DELETE | /kris/exceptions/{id} | Delete an exception |
Reports
| Method | Endpoint | Description |
|---|
GET | /reports/types | List available report types |
POST | /reports/generate | Generate a report (query param: reportType) |
POST | /reports/generate/{type} | Generate a report (path param) |
POST | /reports/export | Export report to CSV |
PAM Accounts
| Method | Endpoint | Description |
|---|
GET | /pam-accounts | List PAM accounts |
POST | /pam-accounts | Create 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-import | Bulk import from CSV |
GET | /pam-accounts/csv-template | Download import template |
GET | /pam-accounts/stats | PAM account statistics |
PAM Reconciliation
| Method | Endpoint | Description |
|---|
GET | /pam-reconciliation | Get reconciliation results |
POST | /pam-reconciliation/run | Execute reconciliation |
POST | /pam-reconciliation/{id}/link | Link account to PAM account |
DELETE | /pam-reconciliation/{id}/link/{pamId} | Unlink |
POST | /pam-reconciliation/bulk-link | Bulk link |
GET | /pam-reconciliation/stats | Reconciliation statistics |
Users (Admin)
| Method | Endpoint | Description |
|---|
GET | /users | List users |
POST | /users | Create a user |
GET | /users/{id} | Get user details |
PUT | /users/{id} | Update a user |
POST | /users/{id}/activate | Activate a user |
POST | /users/{id}/deactivate | Deactivate a user |
POST | /users/{id}/reset-password | Reset password |
API Keys (Admin, Enterprise)
| Method | Endpoint | Description |
|---|
GET | /api-keys | List API keys |
POST | /api-keys | Create an API key |
POST | /api-keys/{id}/enable | Enable a key |
POST | /api-keys/{id}/disable | Disable a key |
DELETE | /api-keys/{id} | Delete a key |
Audit Logs (Admin)
| Method | Endpoint | Description |
|---|
GET | /audit-logs | List audit logs (filterable) |
GET | /audit-logs/action-types | List available action types |
Settings (Admin)
| Method | Endpoint | Description |
|---|
GET | /settings | List all settings |
GET | /settings/map | Get settings as key-value map |
GET | /settings/{key} | Get a single setting |
PUT | /settings/{key} | Update a setting |
PUT | /settings/bulk | Batch update settings |
Password Policy (Admin)
| Method | Endpoint | Description |
|---|
GET | /password-policy | Get current policy |
PUT | /password-policy | Update policy |
OIDC (Admin, Enterprise)
| Method | Endpoint | Description |
|---|
GET | /oidc/status | Get OIDC configuration status |
GET | /oidc/config | Get OIDC configuration |
PUT | /oidc/config | Update OIDC configuration |
DELETE | /oidc/config | Delete OIDC configuration |
Licence
| Method | Endpoint | Description |
|---|
GET | /licenses/status | Get current licence status |
GET | /licenses/features | Get available features and permissions |
POST | /licenses/activate | Activate a licence key |
POST | /licenses/preview | Preview a licence key before activating |
POST | /licenses/deactivate | Deactivate the current licence |
Version
| Method | Endpoint | Description |
|---|
GET | /version | Get application version and build info |