API Reference

Complete REST API reference for the Sovra API Gateway. All endpoints except health probes require authentication via mTLS or JWT.

Base URL: https://<sovra-host>:<port>

Health & Metrics

These endpoints do not require authentication.

GET /health

Returns health status of all components.

Response:

{
  "status": "healthy",
  "version": "2026.4.82",
  "components": {
    "database": {"status": "healthy"},
    "vault": {"status": "healthy"},
    "opa": {"status": "healthy"}
  }
}

SSO Config

GET /api/v1/sso-config

Discover SSO configuration for client login. No authentication required.

Response: 200

{
  "issuer_url": "https://idp.example.org",
  "client_id": "sovra"
}

Workspaces

POST /api/v1/workspaces

Create a new workspace.

Request:

{
  "name": "genomics-data",
  "group_id": "group-123",
  "classification": "CONFIDENTIAL",
  "mode": "standard",
  "purpose": "Shared genomics research",
  "crk_signature": "<base64>"
}

The group_id binds the workspace to an identity group for access control. The deprecated participants array field is still accepted but group_id is preferred.

Response: 201 — Workspace object

GET /api/v1/workspaces

List all workspaces.

Query parameters:

Response: 200 — {"workspaces": [...], "count": 42}

GET /api/v1/workspaces/{id}

Get workspace by ID.

Response: 200 — Workspace object

PUT /api/v1/workspaces/{id}

Update a workspace.

Request:

{
  "purpose": "Updated purpose",
  "classification": "SECRET",
  "mode": "airgap",
  "signature": "<base64>"
}

All fields are optional.

Response: 200 — Updated workspace

DELETE /api/v1/workspaces/{id}

Delete a workspace.

Request:

{
  "signatures": {"org-a": "<base64>", "org-b": "<base64>"}
}

Response: 204

POST /api/v1/workspaces/{id}/encrypt

Encrypt data using workspace DEK.

Request:

{
  "plaintext": "<base64>",
  "context": {"key": "value"}
}

Response: 200 — {"ciphertext": "<base64>"}

POST /api/v1/workspaces/{id}/decrypt

Decrypt data using workspace DEK.

Request:

{
  "ciphertext": "<base64>",
  "context": {"key": "value"}
}

Response: 200 — {"plaintext": "<base64>"}

POST /api/v1/workspaces/{id}/rotate-dek

Rotate the Data Encryption Key.

Request:

{
  "signature": "<base64>"
}

Response: 204

POST /api/v1/workspaces/{id}/extend

Extend workspace expiration.

Request:

{
  "expires_at": "2027-01-01T00:00:00Z",
  "signature": "<base64>"
}

Response: 204

POST /api/v1/workspaces/{id}/invite

Invite an organization to a workspace.

Request:

{
  "org_id": "org-b",
  "signature": "<base64>"
}

Response: 201 — Invitation object

POST /api/v1/workspaces/{id}/accept-invitation

Request:

{
  "org_id": "org-b",
  "signature": "<base64>"
}

Response: 204

POST /api/v1/workspaces/{id}/decline-invitation

Request:

{
  "org_id": "org-b"
}

Response: 204

POST /api/v1/workspaces/{id}/request-access

Request access to a workspace (resolves via group membership).

Request:

{
  "group_id": "group-123",
  "signature": "<base64>"
}

Response: 200 — Access result

Workspace Admissions

Tiered admission control for workspace access. Admissions are required for SECRET and CRK-protected workspaces; CONFIDENTIAL workspaces auto-admit via group membership.

POST /api/v1/workspaces/{id}/admissions

Grant an identity explicit admission to a workspace.

Request:

{
  "identity_id": "user-456",
  "identity_type": "user",
  "org_id": "org-a"
}

Identity types: admin, user, service, device

Response: 201 — WorkspaceAdmission object

GET /api/v1/workspaces/{id}/admissions

List all admissions for a workspace.

Response: 200 — {"admissions": [...], "count": 3}

GET /api/v1/workspaces/{id}/admissions/{identityId}

Get admission status for a specific identity.

Response: 200 — WorkspaceAdmission object

DELETE /api/v1/workspaces/{id}/admissions/{identityId}

Revoke an identity’s admission to a workspace.

Response: 204

POST /api/v1/workspaces/{id}/archive

Archive a workspace.

Request:

{
  "signature": "<base64>"
}

Response: 204

POST /api/v1/workspaces/{id}/export

Export workspace as a portable bundle.

Response: 200 — WorkspaceBundle JSON

POST /api/v1/workspaces/import

Import workspace from a bundle.

Request: WorkspaceBundle JSON

Response: 201 — Created workspace

Federation

POST /api/v1/federation/init

Initialize federation for the organization.

Request:

{
  "org_id": "org-a",
  "crk_signature": "<base64>"
}

Response: 200 — Init result with federation certificate

POST /api/v1/federation/establish

Establish federation with a partner.

Request:

{
  "partner_org_id": "org-b",
  "partner_url": "https://partner.example.org",
  "partner_cert": "<base64>",
  "partner_csr": "<base64>",
  "crk_signature": "<base64>"
}

Response: 201 — Federation object

GET /api/v1/federation

List all federation partnerships.

Response: 200 — {"federations": [...], "count": 3}

GET /api/v1/federation/{partnerId}

Get federation status with a partner.

Response: 200 — Federation object

DELETE /api/v1/federation/{partnerId}

Revoke federation with a partner.

Request:

{
  "signature": "<base64>",
  "notify_partner": true,
  "revoke_certs": true
}

Response: 204

GET /api/v1/federation/health

Health check all federation partnerships.

Response: 200 — {"results": {...}}

POST /api/v1/federation/{partnerId}/renew-cert

Renew the federation certificate with a partner.

Request:

{
  "signature": "<base64>"
}

Response: 200 — Renewed certificate details

POST /api/v1/federation/certificate/import

Import a partner’s federation certificate.

Request:

{
  "partner_org_id": "org-b",
  "certificate": "<base64>",
  "signature": "<base64>"
}

Response: 204

Policies

POST /api/v1/policies

Create a new OPA Rego policy.

Request:

{
  "name": "data-access",
  "workspace": "ws-123",
  "rego": "package sovra.workspace...",
  "crk_signature": "<base64>"
}

Response: 201 — Policy object

GET /api/v1/policies/{id}

Get policy by ID.

Response: 200 — Policy object

PUT /api/v1/policies/{id}

Update a policy.

Request:

{
  "rego": "package sovra.workspace...",
  "signature": "<base64>"
}

Response: 200 — Updated policy

DELETE /api/v1/policies/{id}

Delete a policy.

Request:

{
  "signature": "<base64>"
}

Response: 204

GET /api/v1/policies/workspace/{workspaceId}

Get all policies for a workspace.

Response: 200 — {"policies": [...], "count": 2}

POST /api/v1/policies/evaluate

Evaluate a policy against input.

Request:

{
  "actor": "user@example.org",
  "role": "researcher",
  "operation": "decrypt",
  "workspace": "ws-123",
  "purpose": "data analysis",
  "metadata": {}
}

Response: 200 — {"allowed": true, "deny_reason": "", "eval_time_ms": 5}

POST /api/v1/policies/validate

Validate Rego policy syntax.

Request:

{
  "rego": "package sovra.workspace..."
}

Response: 200 — {"valid": true}

Audit

GET /api/v1/audit

Query audit events.

Query parameters:

Response: 200 — {"events": [...], "count": 150}

GET /api/v1/audit/{id}

Get audit event by ID.

Response: 200 — AuditEvent object

POST /api/v1/audit/export

Export audit logs.

Request:

{
  "org_id": "org-a",
  "workspace": "ws-123",
  "event_type": "workspace.access",
  "since": "2026-01-01T00:00:00Z",
  "until": "2026-02-01T00:00:00Z",
  "format": "json"
}

Formats: json, csv

Response: 200 — Binary file download

GET /api/v1/audit/stats

Get audit statistics.

Query parameters:

Response: 200 — AuditStats object

POST /api/v1/audit/verify

Verify audit log integrity.

Request:

{
  "since": "2026-01-01T00:00:00Z",
  "until": "2026-02-01T00:00:00Z"
}

Response: 200 — {"valid": true, "since": "...", "until": "..."}

Edge Nodes

POST /api/v1/edges

Register a new edge node.

Request:

{
  "name": "edge-eu-west",
  "vault_address": "https://vault.eu-west.example.org:8200",
  "vault_token": "hvs.xxx",
  "vault_ca_cert": "<pem>",
  "classification": "CONFIDENTIAL",
  "region": "eu-west",
  "tags": {"env": "production"}
}

Response: 201 — EdgeNode object

GET /api/v1/edges

List edge nodes.

Response: 200 — {"edges": [...], "count": 5}

GET /api/v1/edges/{id}

Get edge node by ID.

Response: 200 — EdgeNode object

DELETE /api/v1/edges/{id}

Unregister an edge node.

Response: 204

GET /api/v1/edges/{id}/health

Health check an edge node.

Response: 200 — HealthStatus object

POST /api/v1/edges/{id}/sync/policies

Sync policies to an edge node.

Request:

{
  "policies": [...]
}

Response: 204

POST /api/v1/edges/{id}/sync/keys

Sync workspace keys to an edge node.

Request:

{
  "workspace_id": "ws-123",
  "wrapped_dek": "<base64>"
}

Response: 204

GET /api/v1/edges/{id}/sync/status

Get edge node sync status.

Response: 200 — SyncStatus object

Customer Root Keys (CRK)

POST /api/v1/crk/generate

Generate a new CRK with Shamir secret sharing.

Request:

{
  "org_id": "org-a",
  "total_shares": 5,
  "threshold": 3
}

Response: 200 — CRK result with shares

POST /api/v1/crk/sign

Sign data with CRK shares.

Request:

{
  "shares": [{"index": 1, "data": "<base64>"}, ...],
  "public_key": "<base64>",
  "data": "<base64>"
}

Response: 200 — {"signature": "<base64>"}

POST /api/v1/crk/verify

Verify a CRK signature.

Request:

{
  "public_key": "<base64>",
  "data": "<base64>",
  "signature": "<base64>"
}

Response: 200 — {"valid": true}

POST /api/v1/crk/rotate

Start CRK rotation ceremony.

Request:

{
  "org_id": "org-a",
  "threshold": 3
}

Response: 200 — Ceremony object

POST /api/v1/crk/ceremony/start

Start a key ceremony.

Request:

{
  "org_id": "org-a",
  "operation": "generate",
  "threshold": 3
}

Response: 200 — Ceremony object

POST /api/v1/crk/ceremony/{id}/share

Add a share to a ceremony.

Request:

{
  "share": {"index": 1, "data": "<base64>"}
}

Response: 204

POST /api/v1/crk/ceremony/{id}/complete

Complete a ceremony.

Request:

{
  "witness": "admin@example.org"
}

Response: 200 — Ceremony result

DELETE /api/v1/crk/ceremony/{id}

Cancel a ceremony.

Response: 204

CRK Generation Ceremony (Password-Protected Shares)

POST /api/v1/crk/generate-ceremony/start

Start a password-protected CRK generation ceremony.

Request:

{
  "org_id": "org-a",
  "total_shares": 5,
  "threshold": 3
}

Response: 200 — GenerationCeremony object

POST /api/v1/crk/generate-ceremony/{id}/seed

Submit a custodian’s password-derived seed for share encryption.

Request:

{
  "index": 1,
  "custodian_name": "Alice",
  "derived_key": "<base64>",
  "salt": "<base64>"
}

Response: 204

GET /api/v1/crk/generate-ceremony/{id}

Get the status of a generation ceremony.

Response: 200 — GenerationCeremony object

POST /api/v1/crk/generate-ceremony/{id}/complete

Complete the ceremony and generate the CRK with encrypted shares.

Response: 200 — Ceremony result with encrypted shares

DELETE /api/v1/crk/generate-ceremony/{id}

Cancel a generation ceremony.

Response: 204

GET /api/v1/crk/shares/{crkId}/{index}

Get an encrypted share by CRK ID and share index.

Response: 200 — EncryptedCRKShare object

Identities

Admins

POST /api/v1/identities/admins:

{
  "email": "admin@example.org",
  "name": "Admin User",
  "role": "security_admin"
}

Roles: super_admin, security_admin, operations_admin, auditor

POST /api/v1/identities/admins/{id}/certificate/renew

Renew an admin’s mTLS certificate.

Response: 200 — New certificate

PUT /api/v1/identities/admins/{id}:

{
  "email": "new@example.org",
  "name": "New Name",
  "role": "auditor",
  "active": false
}

All fields are optional. Set active to false to disable, true to enable.

POST /api/v1/identities/admins/{id}/mfa/verify:

{
  "totp_code": "123456"
}

Users

POST /api/v1/identities/users/sso:

{
  "provider": "azure_ad",
  "subject": "sub-123",
  "email": "user@example.org",
  "name": "User Name",
  "groups": ["researchers"]
}

Providers: azure_ad, okta, google

Services

POST /api/v1/identities/services:

{
  "name": "data-pipeline",
  "description": "ETL pipeline service",
  "auth_method": "approle"
}

Auth methods: approle, kubernetes, cert

Devices

POST /api/v1/identities/devices:

{
  "device_name": "edge-sensor-1",
  "device_type": "sensor",
  "cert_serial": "AA:BB:CC",
  "cert_expiry": "2027-01-01T00:00:00Z"
}

Groups

POST /api/v1/identities/groups:

{
  "name": "researchers",
  "description": "Research team",
  "vault_policies": ["read-genomics"]
}

GET /api/v1/identities/groups/{id}:

{
  "id": "group-123",
  "name": "researchers",
  "description": "Research team",
  "vault_policies": ["read-genomics"],
  "members": [
    {"identity_id": "user-456", "identity_type": "user"}
  ],
  "created_at": "2026-01-01T00:00:00Z"
}

POST /api/v1/identities/groups/{id}/members:

{
  "identity_id": "user-456",
  "identity_type": "user"
}

Identity types: admin, user, service, device

Roles

POST /api/v1/identities/roles:

{
  "name": "data-reader",
  "description": "Read-only data access",
  "permissions": [{"resource": "workspace", "action": "read"}]
}

GET /api/v1/identities/roles/{id}:

{
  "id": "role-123",
  "name": "data-reader",
  "description": "Read-only data access",
  "permissions": [{"resource": "workspace", "action": "read"}],
  "assignments": [
    {"identity_id": "user-456", "identity_type": "user", "assigned_by": "admin-123"}
  ],
  "created_at": "2026-01-01T00:00:00Z"
}

POST /api/v1/identities/roles/{id}/assign:

{
  "identity_id": "user-456",
  "identity_type": "user",
  "assigned_by": "admin-123"
}

Certificates

POST /api/v1/certificates/issue

Request:

{
  "common_name": "api.example.org",
  "alt_names": ["api2.example.org"],
  "ttl": "8760h"
}

Response: 200 — Certificate with private key, certificate chain, serial number

POST /api/v1/certificates/revoke

Request:

{
  "serial_number": "AA:BB:CC:DD"
}

Response: 204

POST /api/v1/certificates/tidy

Request:

{
  "safety_buffer": "72h"
}

Response: 200 — {"message": "tidy operation started"}

Emergency Access

Break-glass emergency access for critical situations.

POST /api/v1/emergency-access/request

Request:

{
  "org_id": "org-a",
  "reason": "Critical security incident"
}

Response: 201 — AccessRequest object

GET /api/v1/emergency-access

Query parameters:

POST /api/v1/emergency-access/{id}/verify

Request:

{
  "signature": "<base64>"
}

Response: 204

Account Recovery

Recovery using CRK share reconstruction.

POST /api/v1/account-recovery/initiate

Request:

{
  "admin_id": "admin-123",
  "recovery_type": "lost_credentials",
  "reason": "Lost credentials"
}

Recovery types: lost_credentials, locked_account

Response: 201 — Recovery object

Compliance Reports

On-demand compliance report generation.

POST /api/v1/compliance/reports/summary

Request:

{
  "org_id": "org-a",
  "since": "2026-01-01T00:00:00Z",
  "until": "2026-02-01T00:00:00Z"
}

Response: 200 — ComplianceReport object

POST /api/v1/compliance/reports/gdpr-dsar

Request:

{
  "org_id": "org-a",
  "subject_id": "user-123"
}

Response: 200 — ComplianceReport object

POST /api/v1/compliance/reports/access-review

Request:

{
  "org_id": "org-a",
  "since": "2026-01-01T00:00:00Z",
  "until": "2026-02-01T00:00:00Z"
}

Response: 200 — ComplianceReport object

Rotation Policies

Automatic key rotation policies for workspaces.

PUT /api/v1/workspaces/{id}/rotation-policy

Request:

{
  "max_age": "720h",
  "enabled": true
}

Response: 200 — RotationPolicy object

GET /api/v1/workspaces/{id}/rotation-policy

Response: 200 — RotationPolicy object (or 404 if none set)

Backups

Encrypted backup and restore operations. Backup payloads are encrypted at rest using the organization’s KEK via Vault transit. Restore is restricted to the same organization or a clean (empty) instance.

POST /api/v1/backups

Create an encrypted backup of the caller’s organization data (workspaces, federations, policies).

Request:

{
  "type": "full",
  "crk_signature": "<base64>"
}

Response: 201 — Backup object

GET /api/v1/backups

List all backups for the caller’s organization.

Response: 200

{
  "backups": [...],
  "count": 2
}

GET /api/v1/backups/{id}

Get details of a specific backup.

Response: 200 — Backup object

POST /api/v1/backups/{id}/restore

Restore from a backup. The caller’s organization must match the backup’s organization, or the target instance must be clean (no existing organizations). The encrypted payload is decrypted and its SHA-256 checksum is verified before re-importing data.

Request:

{
  "crk_signature": "<base64>"
}

Response: 204 — No Content

Admin Enrollment

Unauthenticated endpoints for initial admin setup.

POST /api/v1/bootstrap/admin

Bootstrap the first admin on a clean instance. Only succeeds when no admins exist.

Request:

{
  "email": "admin@example.org",
  "name": "First Admin",
  "crk_signature": "<base64>"
}

Response: 201 — Admin object with enrollment token

POST /api/v1/enrollment/admins/{id}

Complete enrollment using the enrollment token. Generates mTLS certificate.

Request:

{
  "enrollment_token": "<token>",
  "csr": "<base64-pem>"
}

Response: 200 — Signed certificate

Messages

End-to-end encrypted direct messaging between organizations.

POST /api/v1/messages

Send a direct message.

Request:

{
  "recipient_org_id": "org-b",
  "recipient_id": "admin-456",
  "subject": "Federation certificate renewal",
  "body": "<base64-encrypted>",
  "expires_at": "2026-03-01T00:00:00Z"
}

Response: 201 — Message object

GET /api/v1/messages

List inbox messages.

Query parameters:

Response: 200 — {"messages": [...]}

GET /api/v1/messages/sent

List sent messages.

Response: 200 — {"messages": [...]}

GET /api/v1/messages/{id}

Read a message. Marks it as read.

Response: 200 — Message object

POST /api/v1/messages/deliver

Deliver a message from a federated partner (server-to-server).

Request: Message object

Response: 201

Activity

Activity feed for audit and monitoring.

GET /api/v1/activity

List recent activity events.

Query parameters:

Response: 200 — {"events": [...]}

POST /api/v1/activity/export

Export activity log to file.

Request:

{
  "since": "2026-01-01T00:00:00Z",
  "until": "2026-02-01T00:00:00Z",
  "format": "json"
}

Response: 200 — Binary file download