API reference

RapidValue exposes a REST API. The full OpenAPI spec is auto-generated from the FastAPI backend and lives at:

https://<tenant>.rapidvalue.be/openapi.json
https://<tenant>.rapidvalue.be/docs       (Swagger UI)
https://<tenant>.rapidvalue.be/redoc      (ReDoc)

This page is a high-level orientation — go to the live spec for exact schemas and try-it-out.

Authentication

All endpoints (except /health + login) require a bearer token:

curl -H "Authorization: Bearer <token>" \
  https://<tenant>.rapidvalue.be/api/v1/identities

Tokens are JWT-shaped. Two flavors:

• User tokens — issued by POST /api/v1/auth/login for human users
• Service tokens — issued by an admin under Settings → API tokens for integrations
• Agent tokens — issued at agent registration; used only on the agent spine endpoints (/agent/*)

Tenant scoping

Every request is scoped to the tenant inferred from the bearer token. Admin users on the control plane can use X-Tenant-Id header to act across tenants (audit-logged).

Pagination

List endpoints accept ?limit= (default 50, max 500) and ?offset= query params:

GET /api/v1/identities?limit=100&offset=200

Response shape:

{
  "items": [...],
  "total": 1247,
  "limit": 100,
  "offset": 200
}

Some heavy endpoints support cursor-based pagination (?cursor=<opaque_token>) — check the spec per endpoint.

Role-based scoping

The API enforces role-based data visibility automatically:

• Manager — sees only direct + indirect reports' data
• Resource owner — sees only identities granted to their resources
• Admin — sees everything in the tenant
• Auditor — sees everything, can't write

You don't need to filter manually; the backend does it.

Connector protocol

Custom connectors implement the ConnectorProtocol v1 Pydantic envelope. See app/domain/connector_protocol/v1.py in the backend repo for the full schemas. Sketch:

class SyncRequest(BaseModel):
    connector_business_id: str
    incremental: bool
    last_sync_at: datetime | None
    auth_config: dict

class SyncResponse(BaseModel):
    success: bool
    identities: list[RemoteIdentity]
    accounts: list[RemoteAccount]
    entitlements: list[RemoteEntitlement]
    grants: list[RemoteGrant]
    error: str | None

All connector calls go through the ConnectorDispatcher — in hosted mode it calls the connector directly, in agent mode it routes through the AgentProxyConnector. Same call signature either way.

Key endpoint groups

Prefix	Purpose
/api/v1/auth/*	Login, token refresh
/api/v1/identities/*	Identity CRUD + sync triggers
/api/v1/accounts/*	Account lifecycle
/api/v1/entitlements/*	Entitlement catalog + grants
/api/v1/connectors/*	Connector instances + sync runs
/api/v1/role-mining/*	Mining runs, opportunities, formalize
/api/v1/access-requests/*	Catalog, requests, decisions
/api/v1/approval-rules/*	Approval-chain configuration
/api/v1/certifications/*	Periodic + event-triggered reviews
/api/v1/decision-tasks/*	Unified inbox
/api/v1/policies/*	AccessGrantPolicy, SoD, mitigation
/api/v1/sector-packs/*	Pack install/uninstall
/api/v1/poc/*	POC mode, take-home report
/api/v1/agent/*	Tier-3 agent spine
/api/v1/audit-events/*	Audit log

Webhooks

Outbound webhooks for key events — configure in Settings → Webhooks:

• identity.created / identity.updated / identity.deactivated
• request.submitted / request.approved / request.rejected
• certification.completed
• agent.online / agent.offline

Webhook delivery uses exponential backoff (max 5 attempts over 6 hours).

Rate limits

Default: 100 requests/second per token. Burst up to 200. Contact us if you need higher — sync endpoints often run hot during onboarding and we can raise the limit for the duration.

Idempotency

Write endpoints accept Idempotency-Key header (UUID, your choice). Duplicate requests with the same key within 24h return the original response. Useful for retries on flaky networks.

Integration patterns

Pattern 1 — HR-driven joiner

Your HR system POSTs to a webhook URL when a new employee record is created. The webhook handler calls:

POST /api/v1/identities
{
  "external_id": "hr-12345",
  "email": "alice@yourco.com",
  "first_name": "Alice", "last_name": "Smith",
  "department": "Engineering",
  "manager_external_id": "hr-09876"
}

Birthrights from the sector pack fire automatically; baseline access is provisioned.

Pattern 2 — ITSM-backed access requests

Your service desk wants requests to originate from tickets. The handler calls:

POST /api/v1/access-requests
{
  "requested_for_identity_id": "...",
  "requested_resources": [{"role_id": "..."}],
  "justification": "Ticket INC-12345: new hire onboarding",
  "external_reference": "INC-12345"
}

Decisions flow back via webhook → your ITSM updates the ticket.

Pattern 3 — Long-running sync orchestration

For initial onboardings of large directories (50k+ identities), call:

POST /api/v1/connectors/{id}/sync
{
  "incremental": false,
  "max_records": null,
  "chunk_size": 1000,
  "callback_url": "https://your-orchestrator/sync-progress"
}

The control plane streams progress to your callback. Useful for embedding sync status in your own dashboards.