API Reference

Base URL

https://api.quantumapi.eu/api/v1

Authentication — single credential

Every request authenticates with the X-Api-Key header. The key alone is sufficient — there is no JWT exchange, no session cookie, no second credential. The middleware order is enforced server-side (ApiKeyAuthorizationHandler runs before any other authorization handler), so a valid API key produces an authenticated tenant context for the whole request without needing a Bearer token alongside it.

curl https://api.quantumapi.eu/api/v1/applications \
  -H "X-Api-Key: qapi_..."

API key scopes

Each API key carries an explicit list of scopes. A scope grants the corresponding HTTP verbs on its resource —:read covers GET, :write covers POST/PUT/PATCH/DELETE. Calls without the right scope return 403 witherror: "insufficient_scope".

?include= — opt-in field hydration

Several GET endpoints return a minimal projection by default and let you ask for additional fields via the include query parameter (comma-separated). Two shortcuts are supported on every endpoint that accepts include: metadata selects every supported metadata field, andall selects everything (including the secret value where applicable).

# Get a secret with custom fields, notes and labels in one call
GET /api/v1/secrets/sec_abc123?include=customFields,notes,labels

# Or use the metadata shortcut
GET /api/v1/secrets/sec_abc123?include=metadata

# Public key with rotation history fields
GET /api/v1/keys/key_xyz789/public?include=lastRotatedAt,labels,state

Settings & Security RBAC

Tenant-wide configuration changes require an elevated role. PATCH /api/v1/settings/security is restricted to tenant:owner and tenant:admin; tenant:developer,tenant:viewer, and any API key (regardless of scopes) receive 403 witherror: "forbidden". The same rule applies to other PATCH /api/v1/settings/*endpoints that mutate security or compliance posture.

PATCH /api/v1/settings/security
X-Api-Key: qapi_...                       # API key → 403, even with settings:write
# (use a session token from a tenant:admin/owner browser sign-in instead)

End-user lifecycle endpoints

End-user state transitions are atomic across the Identity context (login enabled / blocked) and the EaaS context (end-user record). On /block and /unblock a save failure on the EaaS save triggers a compensating revert on Identity, so the two contexts cannot drift. /permanent reorders deletion so Identity removal happens before the EaaS cascade — if the cascade fails partway, a retry self-heals without orphaning the Identity user. See #674.

Non-blocking team invitations

POST /api/v1/team/invitations returns within milliseconds even when SMTP is slow. The response is sent as soon as the invitation row is persisted; the invitation email is dispatched on a background task with a fresh DI scope, so an SMTP timeout (up to ~30s upstream) no longer blocks the HTTP request. The response payload includes emailDispatchStatus: "queued" so clients can show a "sending…" state and surface failures via the audit log.

POST /api/v1/team/invitations
X-Api-Key: qapi_...
Content-Type: application/json

{
  "email": "newhire@example.com",
  "role": "tenant:developer"
}

# Response (typically <50ms)
{
  "invitationId": "inv_abc123",
  "email": "newhire@example.com",
  "role": "tenant:developer",
  "expiresAt": "2026-05-08T12:00:00Z",
  "emailDispatchStatus": "queued"
}

Core Endpoints