API reference

The machine API is tenant-scoped and credential-scoped. Create and rotate API credentials in the governed administrator surface; the secret is shown once. Use the smallest scope that reaches the endpoint you need.

Base path:

https://<your-rapidvalue-host>/api/v1/api-gateway

Authentication

Send the issued credential in the X-Api-Key header. Never place it in a query string or documentation ticket.

Start with:

GET /api/v1/api-gateway/whoami
X-Api-Key: <secret>

The response identifies the credential, tenant and effective scopes. A credential cannot select another tenant in a request.

Supported scopes and endpoints

Scope	Method and path	Purpose
identities:read	GET /identities, GET /identities/count	List the scoped identity population
accounts:read	GET /accounts	List accounts
entitlements:read	GET /entitlements	List entitlements
access-requests:read	GET /access-requests	List access requests
certifications:read	GET /certifications	List certification campaigns
audit:read	GET /audit	List immutable audit events, newest first
reports:read	GET /reports	List shared or public report definitions visible to a machine principal
reports:read	GET /api/v1/report-feeds/{report_id}.csv	Download the latest completed run for a report
identities:write	PUT /identities/{source_external_id}	Idempotently create or update one human identity as the API source
identities:write	POST /identities:batch	Apply up to 500 isolated identity items with partial-success results
onboarding:write	POST /api/v1/onboarding-cases/{case_id}/gates/{gate_id}/integration-result	Submit a provider gate result
onboarding:write	POST /api/v1/intake-cases/{case_id}/gates/{gate_id}/integration-result	Submit a staged-intake gate result

Only scopes backed by an enforced endpoint are issuable. Other resource-write scopes are not advertised.

Pagination

List endpoints accept:

?offset=0&limit=100

Responses include an items array and page metadata. Follow the returned total and offset rather than assuming that a short page means the underlying source is complete.

Identity write

PUT /api/v1/api-gateway/identities/HR-1042
X-Api-Key: <secret>
Content-Type: application/json

{
  "first_name": "Amina",
  "last_name": "Diallo",
  "email": "amina.diallo@example.com",
  "employee_id": "1042",
  "identity_type": "employee",
  "status": "active",
  "department": "Finance"
}

A new identity returns 201; an update or idempotent no-op returns 200. Unknown top-level fields and non-human identity types are rejected. There is no machine DELETE for identity erasure.

If another source owns the identity, the default response is 409. With the credential's explicit partial-merge option, only the safe field set is applied and the response names the owning source and skipped fields.

Batch write

{
  "items": [
    {
      "source_external_id": "HR-1042",
      "status": "active",
      "department": "Finance"
    }
  ]
}

The maximum is 500 items. Each item has its own savepoint: a validation or source conflict is returned on that item and does not roll back successful siblings. Re-sending the same accepted values produces noop results.

Errors

Status	Meaning
400	Malformed request
401	Missing, invalid, expired or revoked credential
403	Credential is valid but lacks the required scope
409	Another source owns the identity and partial merge is not allowed
422	Request shape, value or batch size is invalid
429	Deployment rate limit reached
5xx	Service failure; verify the target state before retrying a write

Credential operations

Administrators manage credentials under /api/v1/api-credentials: list issuable scopes, create, inspect, rotate, revoke, update and inspect usage. Management endpoints use the signed-in user session and administrator/auditor role checks; they are not machine-gateway endpoints.

See API access governance for lifecycle, secret handling, audit and blast-radius controls.