{ "openapi": "3.1.1", "info": { "title": "QAudit Admin API", "description": "The QAudit **Admin API** is the operator-facing management side of QAudit: the\nautomated path for organization and tenant lifecycle, emitter provisioning,\ncredential issuance, signing-key rotation, and scoped support sessions. It is a\nstandalone service, a sibling of the Audit Gateway and the Data API.\n\n```mermaid\nflowchart LR\n OP[\"Quadient operator\"] --> WG[Web Gateway]\n WG -->|Bearer| ADMIN[Admin API]\n ADMIN -->|qaudit.* events| GW[Audit Gateway]\n GW --> EV[(Audit events)]\n```\n\n### Who calls it\n\nA Quadient operator, through a tool that authenticates to the API. The future\nAdmin Console (a separate consumer) is one such tool, the way the Data Viewer\nconsumes the Data API.\n\n### Authenticating\n\nThe Admin API validates the `Bearer` credential it receives: a Quadient SSO\ntoken relayed by the Web Gateway, or an admin-capable API key, presented as\n`Authorization: Bearer `. The login flow itself runs in the Web\nGateway; this service only validates the relayed credential.\n\n### Resource hierarchy\n\nAn organization is the identity, credential, and signing boundary; tenants are\nsub-scopes within it. Org-scoped resources hang off\n`/organizations/{organization_id}`, and system-scoped resources live under\n`/system`.\n\n### Auditing\n\nEvery mutating operation is recorded as a `qaudit.*` audit event; reads, lists,\nand fetches emit no event.\n\n### Errors\n\nError responses use problem details (`application/problem+json`, RFC 9457): a\n`status`, a short `title`, and a `detail`. A `400` additionally lists per-field\nvalidation messages.\n", "version": "1.0.0" }, "servers": [ { "url": "https://api.admin.nightly.qaudit.ismailbennani.fr/" } ], "paths": { "/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List organizations", "description": "Lists organizations, newest first, each with its display name, creation time, and current signing key (version + fingerprint). Narrow with `search` (a case-insensitive match on the display name) and the `created_after` / `created_before` window. Page with `page` / `page_size`.", "operationId": "ListOrganizations", "parameters": [ { "name": "search", "in": "query", "description": "Case-insensitive substring match on the organization display name.", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "Only organizations created at or after this instant (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Only organizations created at or before this instant (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "1-based page number; defaults to 1.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "page_size", "in": "query", "description": "Page size; defaults to 50 and is clamped to a maximum.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationPage" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Organizations" ], "summary": "Create an organization", "description": "Creates an organization: provisions its per-organization Ed25519 signing key and opens its access-trail chain (whose first event is `qaudit.organization.created.v1`), with the signing key, chain, and `cfg` row written atomically. Tenants are added afterwards through the tenant endpoint. Returns the created organization.", "operationId": "CreateOrganization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}": { "get": { "tags": [ "Organizations" ], "summary": "Get an organization", "description": "Returns one organization by id, with its current signing key (version + fingerprint). Responds `404` when no such organization exists.", "operationId": "GetOrganization", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Organizations" ], "summary": "Edit an organization", "description": "Edits an organization's display name. The change is audited on the organization's chain before it is applied; if it cannot be audited the organization is left unchanged. Responds `404` when no such organization exists.", "operationId": "UpdateOrganization", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/signing-keys": { "get": { "tags": [ "Organizations" ], "summary": "List an organization's signing keys", "description": "Returns the organization's signing keys (newest version first), each with its public key material so an operator can share it with the organization, for example during onboarding. The private key never leaves Vault. Responds `404` when no such organization exists.", "operationId": "ListOrganizationSigningKeys", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationSigningKeyDetails" } } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/signing-keys/{version}/pem": { "get": { "tags": [ "Organizations" ], "summary": "Download an organization signing key (PEM)", "description": "Returns the organization's signing key, by version, as a PEM-encoded public key, the most compatible format to hand to the organization. Responds `404` when no such organization or version exists.", "operationId": "DownloadOrganizationSigningKeyPem", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "path", "description": "Signing-key version.", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "200": { "description": "OK", "content": { "application/x-pem-file": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/signing-keys/{version}/jws": { "get": { "tags": [ "Organizations" ], "summary": "Download an organization signing key (JWS attestation)", "description": "Returns the organization's signing key, by version, as a compact JWS attesting the key under QAudit's identity (signed by the root key), so the organization can verify its provenance. Responds `404` when no such organization or version exists, `503` when attestation is not configured on this deployment.", "operationId": "DownloadOrganizationSigningKeyJws", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "path", "description": "Signing-key version.", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "200": { "description": "OK", "content": { "application/jwt": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/tenants": { "get": { "tags": [ "Tenants" ], "summary": "List an organization's tenants", "description": "Lists the organization's tenants, ordered by display name. Narrow with `search` (a case-insensitive match on the display name and tenant id) and the `onboarded_from` / `onboarded_to` window. Page with `page` / `page_size`. Responds `404` when no such organization exists.", "operationId": "ListTenants", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Case-insensitive substring matched against the display name and tenant id.", "schema": { "type": "string" } }, { "name": "onboarded_from", "in": "query", "description": "Only tenants onboarded at or after this instant (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "onboarded_to", "in": "query", "description": "Only tenants onboarded at or before this instant (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "1-based page number; defaults to 1.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "page_size", "in": "query", "description": "Page size; defaults to 50 and is clamped to a maximum.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPage" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Tenants" ], "summary": "Add a tenant", "description": "Adds a tenant to the organization: opens its access-trail chain (whose first event is `qaudit.tenant.created.v1`, embedding the organization's current signing key), with the chain and `cfg` row written atomically. The `tenant_id` is caller-supplied: non-empty, unique within the organization, and may not start with the reserved `_` prefix. Returns the created tenant.", "operationId": "CreateTenant", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/tenants/{tenant_id}": { "get": { "tags": [ "Tenants" ], "summary": "Get a tenant", "description": "Returns one tenant of the organization by id. Responds `404` when no such tenant belongs to the organization.", "operationId": "GetTenant", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "path", "description": "Opaque tenant identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Tenants" ], "summary": "Edit a tenant", "description": "Edits a tenant's display name. The change is audited on the tenant's chain before it is applied; if it cannot be audited the tenant is left unchanged. Responds `404` when no such tenant belongs to the organization.", "operationId": "UpdateTenant", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "path", "description": "Opaque tenant identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/tenants/{tenant_id}/overview": { "get": { "tags": [ "Tenants" ], "summary": "Get a tenant's operational overview", "description": "Returns an operator's read-only view of a tenant's operational state: its identity, how many events are on its chain and how recently they were ingested, the event types it has emitted, the signing-key version its last event was signed under against the organization's current version, and its data-pack figures. This describes the chain, not its contents; no event payload is exposed. Responds `404` when no such tenant belongs to the organization.", "operationId": "GetTenantOverview", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "path", "description": "Opaque tenant identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOverview" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/credentials": { "get": { "tags": [ "Organization credentials" ], "summary": "List an organization's credentials", "description": "Lists the organization's credentials, newest first, with their lifecycle status and (when revoked) the revocation. The full secret is never returned; each credential carries only its non-secret key prefix, to help recognize it. Page with `page` / `page_size`, narrow to a lifecycle state with `status` (`active`, `expired`, `revoked`), and match names with `search`. The response's `counts` reports how many credentials match the search in each status, independent of the `status` filter.", "operationId": "ListOrganizationCredentials", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "1-based page number; defaults to 1.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "page_size", "in": "query", "description": "Page size; defaults to 50 and is clamped to a maximum.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "status", "in": "query", "description": "Narrow to a lifecycle status: active, expired, or revoked.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Case-insensitive match on the credential name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCredentialPage" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Organization credentials" ], "summary": "Issue an organization credential", "description": "Issues a data-only credential scoped to this organization and returns the secret once, in the response body: it is never shown again and only its hash is stored. The issuance is audited on the organization's chain; if it cannot be audited the credential is not created.", "operationId": "IssueOrganizationCredential", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueOrganizationCredentialRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedOrganizationCredential" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/credentials/{credential_id}": { "get": { "tags": [ "Organization credentials" ], "summary": "Get an organization credential", "description": "Returns one of the organization's credentials by id. The full secret is never returned; the credential carries only its non-secret key prefix, to help recognize it. Responds `404` when no such credential belongs to the organization.", "operationId": "GetOrganizationCredential", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "credential_id", "in": "path", "description": "Identifier of the credential.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCredential" } } } }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/credentials/{credential_id}/rotate": { "post": { "tags": [ "Organization credentials" ], "summary": "Rotate an organization credential", "description": "Regenerates the credential's secret in place (same id and name) and returns the new secret once; the previous secret stops working immediately. The optional `expires_at` in the body renews the credential at the same time: omit it to keep the current expiry, or set it (must be in the future) to reschedule. Rotating a revoked credential, or an expired one without a new future `expires_at`, is rejected. The rotation is audited on the organization's chain before the secret changes; if it cannot be audited the secret is left unchanged.", "operationId": "RotateOrganizationCredential", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "credential_id", "in": "path", "description": "Identifier of the credential.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RotateCredentialRequest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedOrganizationCredential" } } } }, "404": { "description": "Not Found" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/credentials/{credential_id}/revoke": { "post": { "tags": [ "Organization credentials" ], "summary": "Revoke an organization credential", "description": "Revokes the credential; it stops working immediately and the revocation is terminal. Supply an optional `reason` in the request body to record why; it is stored on the credential and carried on the audit event. The revocation is audited on the organization's chain.", "operationId": "RevokeOrganizationCredential", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier of the organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "credential_id", "in": "path", "description": "Identifier of the credential.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RevokeCredentialRequest" } ] } } } }, "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/admin/credentials": { "get": { "tags": [ "Admin API credentials" ], "summary": "List Admin API credentials", "description": "Lists the Admin API credentials, newest first, with their admin access level, lifecycle status, and (when revoked) the revocation. The full secret is never returned; each credential carries only its non-secret key prefix, to help recognize it. Page with `page` / `page_size`, narrow to a lifecycle state with `status` (`active`, `expired`, `revoked`), and match names with `search`. The response's `counts` reports how many credentials match the search in each status, independent of the `status` filter.", "operationId": "ListAdminCredentials", "parameters": [ { "name": "page", "in": "query", "description": "1-based page number; defaults to 1.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "page_size", "in": "query", "description": "Page size; defaults to 50 and is clamped to a maximum.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "status", "in": "query", "description": "Narrow to a lifecycle status: active, expired, or revoked.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Case-insensitive match on the credential name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCredentialPage" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Admin API credentials" ], "summary": "Issue an Admin API credential", "description": "Issues an Admin API credential carrying the requested `admin` access level (`read-only` or `read-write`), which is required. Returns the secret once, in the response body: it is never shown again and only its hash is stored. The issuance is audited on the system chain; if it cannot be audited the credential is not created.", "operationId": "IssueAdminCredential", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueAdminCredentialRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedAdminCredential" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/admin/credentials/{credential_id}": { "get": { "tags": [ "Admin API credentials" ], "summary": "Get an Admin API credential", "description": "Returns an Admin API credential by id. The full secret is never returned; the credential carries only its non-secret key prefix, to help recognize it. Responds `404` when no such Admin API credential exists.", "operationId": "GetAdminCredential", "parameters": [ { "name": "credential_id", "in": "path", "description": "Identifier of the credential.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCredential" } } } }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/admin/credentials/{credential_id}/rotate": { "post": { "tags": [ "Admin API credentials" ], "summary": "Rotate an Admin API credential", "description": "Regenerates the credential's secret in place (same id, name, and access level) and returns the new secret once; the previous secret stops working immediately. The optional `expires_at` in the body renews the credential at the same time: omit it to keep the current expiry, or set it (must be in the future) to reschedule. Rotating a revoked credential, or an expired one without a new future `expires_at`, is rejected. The rotation is audited on the system chain before the secret changes; if it cannot be audited the secret is left unchanged.", "operationId": "RotateAdminCredential", "parameters": [ { "name": "credential_id", "in": "path", "description": "Identifier of the credential.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RotateCredentialRequest" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedAdminCredential" } } } }, "404": { "description": "Not Found" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/admin/credentials/{credential_id}/revoke": { "post": { "tags": [ "Admin API credentials" ], "summary": "Revoke an Admin API credential", "description": "Revokes the credential; it stops working immediately and the revocation is terminal. Supply an optional `reason` in the request body to record why; it is stored on the credential and carried on the audit event. The revocation is audited on the system chain.", "operationId": "RevokeAdminCredential", "parameters": [ { "name": "credential_id", "in": "path", "description": "Identifier of the credential.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RevokeCredentialRequest" } ] } } } }, "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/system/emitters": { "get": { "tags": [ "Emitters" ], "summary": "List the emitter registry", "description": "Lists emitters, newest first, including platform-managed rows so operators see everything that is emitting. Narrow with `search` (a case-insensitive match on the name and emitter id), `managed_by` (`operator` or `platform`), and `status` (`active` or `revoked`); page with `page` / `page_size`. The response's `counts` reports how many emitters match in each kind, independent of the `managed_by` filter but honoring `status`.", "operationId": "ListEmitters", "parameters": [ { "name": "search", "in": "query", "description": "Case-insensitive substring matched against the name and emitter id.", "schema": { "type": "string" } }, { "name": "created_from", "in": "query", "description": "Only emitters created at or after this instant (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "description": "Only emitters created at or before this instant (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "managed_by", "in": "query", "description": "Restrict to operator- or platform-managed rows: `operator` or `platform`; omit for both.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Restrict to a lifecycle state: `active` or `revoked`; omit for both.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "1-based page number; defaults to 1.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "page_size", "in": "query", "description": "Page size; defaults to 50 and is clamped to a maximum.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitterPage" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Emitters" ], "summary": "Provision an emitter", "description": "Issues the emitter's mTLS cert and inserts its registry row, atomically. Supply a `csr` to have the leaf signed from it (no private key is returned), or omit it to receive a platform-generated keypair as a PKCS#12 bundle. The cert is returned once. The new row is operator-managed. The provisioning is audited on the system chain; if it cannot be audited the emitter is not created.", "operationId": "ProvisionEmitter", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionEmitterRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitterWithCertificate" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/system/emitters/{emitter_id}": { "get": { "tags": [ "Emitters" ], "summary": "Get an emitter", "description": "Returns one emitter by id. Responds `404` when no such emitter exists.", "operationId": "GetEmitter", "parameters": [ { "name": "emitter_id", "in": "path", "description": "The emitter's opaque identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Emitter" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Emitters" ], "summary": "Edit an emitter", "description": "Edits the emitter's name and description. The change is audited on the system chain before it is applied; if it cannot be audited the emitter is left unchanged. Responds `404` when no such emitter exists, `403` for a platform-managed row, `409` for a revoked row (revocation is terminal). Cert rotation is a separate operation (`POST /system/emitters/{emitter_id}/cert`).", "operationId": "UpdateEmitter", "parameters": [ { "name": "emitter_id", "in": "path", "description": "The emitter's opaque identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmitterRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Emitter" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/system/emitters/{emitter_id}/cert": { "post": { "tags": [ "Emitters" ], "summary": "Rotate an emitter's cert", "description": "Issues a fresh mTLS cert for the emitter and replaces the cert metadata on its row; the previous cert stops authorizing as soon as the row points at the new one. Supply a `csr` to have the leaf signed from it (no private key is returned), or omit it to receive a platform-generated keypair as a PKCS#12 bundle. The cert is returned once. The rotation is audited on the system chain before it is applied. Responds `404` when no such emitter exists, `403` for a platform-managed row, `409` for a revoked row (revocation is terminal).", "operationId": "RotateEmitterCert", "parameters": [ { "name": "emitter_id", "in": "path", "description": "The emitter's opaque identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitterCertRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitterWithCertificate" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/system/emitters/{emitter_id}/revoke": { "post": { "tags": [ "Emitters" ], "summary": "Revoke an emitter", "description": "Revokes the emitter; its cert stops authorizing immediately and the revocation is terminal. Supply an optional `reason` in the request body to record why; it is carried on the audit event. The revocation is audited on the system chain. Responds `404` when no such emitter exists or it is already revoked, `403` for a platform-managed row.", "operationId": "RevokeEmitter", "parameters": [ { "name": "emitter_id", "in": "path", "description": "The emitter's opaque identifier.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RevokeEmitterRequest" } ] } } } }, "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/support-sessions": { "post": { "tags": [ "Support sessions" ], "summary": "Open a support session", "description": "Opens a scoped, time-bound support session against the organization: audits the opening on the organization's chain (`qaudit.support.session.opened.v1`), mints a short-lived grant for the calling operator, and returns `201` with a redirect to the Data Viewer at the organization scope. The session auto-closes when the grant expires. Requires an operator session (a human operator); responds `404` when no such organization exists, `503` when the opening could not be audited.", "operationId": "OpenSupportSession", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization the session grants a view of.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenSupportSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportSessionResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "tags": [ "Support sessions" ], "summary": "List active support sessions", "description": "Lists the organization's currently-active support sessions, most recently opened first, each with its operator, reason, ticket reference, opened-at, and expiry. A session that has expired or closed is no longer active and is not returned; the audit history lives on the chain.", "operationId": "ListSupportSessions", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization whose active sessions to list.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupportSession" } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/support-sessions/{support_session_id}/grant": { "post": { "tags": [ "Support sessions" ], "summary": "Resume an active support session", "description": "Re-acquires the grant for an already-open support session, for the operator who opened it: re-mints a support token capped at the session's existing expiry and returns `200` with a fresh redirect to the Data Viewer (so an operator who lost the grant can regain access for the remaining window). The session's audited open/close window is unchanged, and no new event is recorded. Requires an operator session; responds `403` when the caller is not the operator who opened the session, `404` when no active session with that id exists for the organization, and `503` when a token could not be issued.", "operationId": "ResumeSupportSession", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization the session grants a view of.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "support_session_id", "in": "path", "description": "Identifier of the session to resume.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportSessionResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/organizations/{organization_id}/support-sessions/{support_session_id}": { "get": { "tags": [ "Support sessions" ], "summary": "Get an active support session", "description": "Returns one active support session by id. Responds `404` when no active session with that id exists for the organization, including once the session has expired or closed (live state, not history).", "operationId": "GetSupportSession", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization the session belongs to.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "support_session_id", "in": "path", "description": "Identifier of the support session.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportSession" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "AdminCapability": { "enum": [ "read-only", "read-write" ], "description": "A credential's Admin API access level. AdminCapability.ReadOnly may call the\nread endpoints (list / get); AdminCapability.ReadWrite may also mutate (issue,\nrotate, revoke, and the other management operations). An authenticated\noperator session is always full read/write. A credential with no Admin API\naccess carries no level (a `null``Admin`)." }, "AdminCredential": { "required": [ "credential_id", "name", "key_prefix", "admin", "status", "creation" ], "type": "object", "properties": { "credential_id": { "type": "string", "description": "Credential identifier.", "example": "00000000-0000-0000-0000-000000000000" }, "name": { "type": "string", "description": "Operator-facing label." }, "key_prefix": { "type": "string", "description": "The non-secret leading fragment of the key, kept to help recognize it. The full key is never stored.", "example": "qa_AbCdEf" }, "admin": { "description": "Admin API access level (`read-only` or `read-write`).", "$ref": "#/components/schemas/AdminCapability" }, "status": { "description": "Lifecycle status as of the response.", "$ref": "#/components/schemas/ApiCredentialStatus" }, "creation": { "description": "When the credential was issued, and by whom.", "$ref": "#/components/schemas/CredentialCreation" }, "expiration": { "oneOf": [ { "type": "null" }, { "description": "Scheduled end of validity; absent when it never expires.", "$ref": "#/components/schemas/CredentialExpiration" } ] }, "revocation": { "oneOf": [ { "type": "null" }, { "description": "When the credential was revoked, by whom, and why; absent while not revoked.", "$ref": "#/components/schemas/CredentialRevocation" } ] }, "last_used_at": { "type": [ "null", "string" ], "description": "Last time the key authenticated a request; absent if never used.", "format": "date-time" } }, "description": "An Admin API credential: a key bound to no organization, carrying an Admin API\naccess level (`admin`). The secret is never returned and only its hash is\nstored; the response carries the non-secret key prefix (the first few\ncharacters) to help recognize the key." }, "AdminCredentialPage": { "required": [ "items", "total", "page", "page_size", "counts" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminCredential" }, "description": "The credentials on this page, newest first." }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total matches across all pages, for the filtered status.", "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The 1-based page number.", "format": "int32" }, "page_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The page size applied.", "format": "int32" }, "counts": { "description": "Per-status match counts for the current search, independent of the status filter.", "$ref": "#/components/schemas/CredentialStatusCounts" } }, "description": "One page of Admin API credentials: the rows for the filtered status, the total\nmatch count for paging, and the per-status counts for the current search\n(across all statuses) so the caller can badge each status view." }, "ApiCredentialStatus": { "enum": [ "active", "expired", "revoked" ], "description": "Lifecycle status of an API credential. Precedence is ApiCredentialStatus.Revoked\n> ApiCredentialStatus.Expired > ApiCredentialStatus.Active: revocation is terminal,\nexpiry is a renewable time bound." }, "CreateOrganizationRequest": { "required": [ "display_name" ], "type": "object", "properties": { "display_name": { "type": "string", "description": "The organization's display name, shown wherever the organization is identified. Required, non-empty." } }, "description": "Request to create an organization. Creating one provisions its signing key and\nopens its access-trail chain; tenants are added afterwards through the tenant\nendpoint." }, "CreateTenantRequest": { "required": [ "tenant_id", "display_name" ], "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The tenant's opaque identifier. Required, non-empty, unique within the\norganization, and may not start with the reserved `_` prefix\n(reserved for platform-written chains)." }, "display_name": { "type": "string", "description": "The tenant's display name. Required, non-empty." } }, "description": "Request to add a tenant to an organization. Creating one opens the tenant's\nchain (its genesis `qaudit.tenant.created.v1`)." }, "CredentialCreation": { "required": [ "at" ], "type": "object", "properties": { "at": { "type": "string", "description": "When the credential was issued.", "format": "date-time", "example": "2026-06-07T12:00:00+00:00" }, "subject": { "type": [ "null", "string" ], "description": "The OIDC subject of the operator that issued it; absent when an API credential issued it or it was unattributed." }, "credential_id": { "type": [ "null", "string" ], "description": "The API credential that issued it; absent when an operator issued it or it was unattributed.", "example": "00000000-0000-0000-0000-000000000000" } }, "description": "When a credential was issued, and by whom. The actor is an operator\n (`subject`) or an API credential (`credential_id`); both are absent\n when the issuance was unattributed." }, "CredentialExpiration": { "required": [ "at" ], "type": "object", "properties": { "at": { "type": "string", "description": "Scheduled end of validity.", "format": "date-time", "example": "2026-12-31T00:00:00+00:00" } }, "description": "When a credential's validity ends. Present only when the credential has a scheduled expiry." }, "CredentialRevocation": { "required": [ "at" ], "type": "object", "properties": { "at": { "type": "string", "description": "When the credential was revoked.", "format": "date-time", "example": "2026-06-08T09:00:00+00:00" }, "subject": { "type": [ "null", "string" ], "description": "The OIDC subject of the operator that revoked it; absent when an API credential revoked it or it was unattributed." }, "credential_id": { "type": [ "null", "string" ], "description": "The API credential that revoked it; absent when an operator revoked it or it was unattributed.", "example": "00000000-0000-0000-0000-000000000000" }, "reason": { "type": [ "null", "string" ], "description": "Why it was revoked, or absent when no reason was recorded." } }, "description": "When a credential was revoked, by whom, and why. Present only on a\n revoked credential. The actor is an operator (`subject`) or an API\n credential (`credential_id`); both are absent when the revocation was\n unattributed." }, "CredentialStatusCounts": { "required": [ "active", "expired", "revoked" ], "type": "object", "properties": { "active": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Credentials usable now.", "format": "int32" }, "expired": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Credentials past their expiry but not revoked.", "format": "int32" }, "revoked": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Revoked credentials.", "format": "int32" } }, "description": "How many credentials match the current search in each lifecycle status,\nindependent of the status the page is filtered to. Lets a caller badge the\nactive / expired / revoked views with their counts at once." }, "Emitter": { "required": [ "emitter_id", "name", "privileged", "managed_by", "cert_thumbprint", "cert_serial", "created_at" ], "type": "object", "properties": { "emitter_id": { "type": "string", "description": "The emitter's opaque identifier.", "example": "pa-prod" }, "name": { "type": "string", "description": "Short human-facing label.", "example": "PA production emitter" }, "description": { "type": [ "null", "string" ], "description": "Operator-facing context for the row, or `null`." }, "privileged": { "type": "boolean", "description": "Whether the emitter may write reserved chains, such as the system chain." }, "managed_by": { "description": "Who owns mutations to this row: `operator` rows are managed here;\n`platform` rows are managed by the platform itself and are read-only\n(mutating one responds `403`).", "$ref": "#/components/schemas/EmitterManagedBy" }, "cert_thumbprint": { "type": "string", "description": "Lower-case hex SHA-256 thumbprint of the emitter's mTLS cert." }, "cert_serial": { "type": "string", "description": "The mTLS cert's serial number." }, "cert_not_after": { "type": [ "null", "string" ], "description": "When the mTLS cert expires (ISO 8601), or `null` when the cert does not expire.", "format": "date-time" }, "revoked_at": { "type": [ "null", "string" ], "description": "When the emitter was revoked (ISO 8601), or `null` while it is active.", "format": "date-time" }, "created_at": { "type": "string", "description": "When the row was created (ISO 8601).", "format": "date-time" } }, "description": "An emitter-registry row: an application authenticated to submit events, with\nits mTLS identity and authorization config. The private key and the issued\ncert artifact are returned only at provision / rotation time, never here." }, "EmitterCertArtifact": { "required": [ "certificate_pem", "ca_chain_pem", "thumbprint" ], "type": "object", "properties": { "certificate_pem": { "type": "string", "description": "The issued leaf certificate, PEM-encoded." }, "ca_chain_pem": { "type": "array", "items": { "type": "string" }, "description": "The issuing CA chain, leaf-to-root, PEM-encoded." }, "pkcs12_base64": { "type": [ "null", "string" ], "description": "The PKCS#12 bundle (leaf + private key + chain), base64-encoded — present\nonly in the platform-generated keypair mode. Shown once: the private key is\nnever stored server-side and cannot be retrieved later, so the caller must\ncapture it from this response (lose it and the emitter must be rotated)." }, "thumbprint": { "type": "string", "description": "Lower-case hex SHA-256 thumbprint of the issued leaf." }, "not_after": { "type": [ "null", "string" ], "description": "When the issued leaf expires (ISO 8601), or `null` when it does not expire.", "format": "date-time" } }, "description": "The issued mTLS cert handed back at provision / rotation, shown once. In the\ncaller-CSR mode it carries the signed leaf and the issuing chain (no private\nkey); in the platform-generated keypair mode it additionally carries the\nPKCS#12 bundle (leaf + private key + chain), base64-encoded." }, "EmitterCertRequest": { "type": "object", "properties": { "csr": { "type": [ "null", "string" ], "description": "A PEM-encoded PKCS#10 certificate signing request. When present, the leaf\nis signed from it and no private key is returned. When absent, a keypair is\ngenerated and returned as a PKCS#12 bundle." } }, "description": "Selects the cert-provisioning mode on provision and on cert rotation: supply\na `csr` to have the leaf signed from it, so the private key never crosses\nthe network (the recommended default), or omit it to receive a\nplatform-generated keypair as a PKCS#12 bundle." }, "EmitterCounts": { "required": [ "operator", "platform" ], "type": "object", "properties": { "operator": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Operator-managed emitters.", "format": "int32" }, "platform": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Platform-managed emitters.", "format": "int32" } }, "description": "How many emitters match the current search in each kind, independent of the\n`managed_by` filter the page is narrowed to. Lets a caller badge the\noperator-managed and platform-managed views with their counts at once." }, "EmitterManagedBy": { "enum": [ "operator", "platform" ], "description": "Who owns mutations to an emitter-registry row (ADR-0027). Determines whether\nthe row is operator-managed through the Admin API or platform-managed by\nplatform-internal automation (in which case it is read-only to operators)." }, "EmitterPage": { "required": [ "items", "total", "page", "page_size", "counts" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Emitter" }, "description": "The emitters on this page, newest first." }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total emitters across all pages.", "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The 1-based page number.", "format": "int32" }, "page_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The page size applied.", "format": "int32" }, "counts": { "description": "How many emitters match the search in each kind, independent of the\n`managed_by` filter, so a caller can badge both kind views at once.", "$ref": "#/components/schemas/EmitterCounts" } }, "description": "One page of the emitter registry: the rows plus the total count. Includes\nplatform-managed rows so operators see everything that is emitting." }, "EmitterWithCertificate": { "required": [ "emitter", "certificate" ], "type": "object", "properties": { "emitter": { "description": "The emitter's current registry row.", "$ref": "#/components/schemas/Emitter" }, "certificate": { "description": "The issued cert artifact.", "$ref": "#/components/schemas/EmitterCertArtifact" } }, "description": "An emitter together with a freshly issued cert artifact — the response to a\nprovision and to a cert rotation. The cert is shown once." }, "HttpValidationProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "IssueAdminCredentialRequest": { "required": [ "name", "admin" ], "type": "object", "properties": { "name": { "type": "string", "description": "Operator-facing label so the credential is recognizable in a list.", "example": "platform automation" }, "admin": { "description": "Admin API access level to grant. Required (`read-only` or `read-write`).", "$ref": "#/components/schemas/AdminCapability" }, "expires_at": { "type": [ "null", "string" ], "description": "Optional scheduled expiry; omit for a credential that never expires.", "format": "date-time" } }, "description": "Request body to issue an Admin API credential. `admin` grants Admin API\naccess and is required (`read-only` or `read-write`)." }, "IssuedAdminCredential": { "required": [ "credential", "secret" ], "type": "object", "properties": { "credential": { "description": "The issued (or rotated) credential's metadata.", "$ref": "#/components/schemas/AdminCredential" }, "secret": { "type": "string", "description": "The secret, shown once. Store it now; it cannot be retrieved later." } }, "description": "The response to issuing or rotating an Admin API credential: the credential\nmetadata plus the one-time secret. The secret is shown only here,\nnever again, and is stored only as a hash." }, "IssuedOrganizationCredential": { "required": [ "credential", "secret" ], "type": "object", "properties": { "credential": { "description": "The issued (or rotated) credential's metadata.", "$ref": "#/components/schemas/OrganizationCredential" }, "secret": { "type": "string", "description": "The secret, shown once. Store it now; it cannot be retrieved later." } }, "description": "The response to issuing or rotating an organization credential: the credential\nmetadata plus the one-time secret. The secret is shown only here,\nnever again, and is stored only as a hash." }, "IssueOrganizationCredentialRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "Operator-facing label so the credential is recognizable in a list.", "example": "SIG production integration" }, "expires_at": { "type": [ "null", "string" ], "description": "Optional scheduled expiry; omit for a credential that never expires.", "format": "date-time" } }, "description": "Request body to issue an organization credential. Organization credentials are\ndata-only by definition (they grant Data API access to their organization), so\nthe body carries no capability flags." }, "OpenSupportSessionRequest": { "required": [ "ticket_reference", "reason" ], "type": "object", "properties": { "ticket_reference": { "type": "string", "description": "The support ticket the session is opened against." }, "reason": { "type": "string", "description": "The operator's declared reason for the session (a free-text audit annotation; it does not restrict access)." } }, "description": "Request to open a support session." }, "Organization": { "required": [ "organization_id", "display_name", "created_at" ], "type": "object", "properties": { "organization_id": { "type": "string", "description": "Organization identifier.", "example": "00000000-0000-0000-0000-000000000000" }, "display_name": { "type": "string", "description": "The organization's display name, shown wherever the organization is identified." }, "created_at": { "type": "string", "description": "When the organization was created.", "format": "date-time", "example": "2026-06-07T12:00:00+00:00" } }, "description": "An organization: the identity, credential, and signing boundary that tenants\nlive inside. Carries its display name and when it was created. The signing\nkeys are read through the signing-keys endpoint, not on this resource." }, "OrganizationCredential": { "required": [ "credential_id", "organization_id", "name", "key_prefix", "status", "creation" ], "type": "object", "properties": { "credential_id": { "type": "string", "description": "Credential identifier.", "example": "00000000-0000-0000-0000-000000000000" }, "organization_id": { "type": "string", "description": "The organization this credential reads.", "example": "00000000-0000-0000-0000-000000000000" }, "name": { "type": "string", "description": "Operator-facing label." }, "key_prefix": { "type": "string", "description": "The non-secret leading fragment of the key, kept to help recognize it. The full key is never stored.", "example": "qa_AbCdEf" }, "status": { "description": "Lifecycle status as of the response.", "$ref": "#/components/schemas/ApiCredentialStatus" }, "creation": { "description": "When the credential was issued, and by whom.", "$ref": "#/components/schemas/CredentialCreation" }, "expiration": { "oneOf": [ { "type": "null" }, { "description": "Scheduled end of validity; absent when it never expires.", "$ref": "#/components/schemas/CredentialExpiration" } ] }, "revocation": { "oneOf": [ { "type": "null" }, { "description": "When the credential was revoked, by whom, and why; absent while not revoked.", "$ref": "#/components/schemas/CredentialRevocation" } ] }, "last_used_at": { "type": [ "null", "string" ], "description": "Last time the key authenticated a request; absent if never used.", "format": "date-time" } }, "description": "An organization credential: a credential scoped to a single organization.\nOrganization credentials are data-only by definition, so no capability is\nreported here. The secret is never returned and only its hash is stored; the\nresponse carries the non-secret key prefix (the first few characters) to help\nrecognize the key." }, "OrganizationCredentialPage": { "required": [ "items", "total", "page", "page_size", "counts" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationCredential" }, "description": "The credentials on this page, newest first." }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total matches across all pages, for the filtered status.", "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The 1-based page number.", "format": "int32" }, "page_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The page size applied.", "format": "int32" }, "counts": { "description": "Per-status match counts for the current search, independent of the status filter.", "$ref": "#/components/schemas/CredentialStatusCounts" } }, "description": "One page of organization credentials: the rows for the filtered status, the\ntotal match count for paging, and the per-status counts for the current search\n(across all statuses) so the caller can badge each status view." }, "OrganizationPage": { "required": [ "items", "total", "page", "page_size" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" }, "description": "The organizations on this page, newest first." }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total organizations across all pages.", "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The 1-based page number.", "format": "int32" }, "page_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The page size applied.", "format": "int32" } }, "description": "One page of organizations: the rows plus the total count so a caller can render\npage numbers." }, "OrganizationSigningKeyDetails": { "required": [ "version", "created_at", "fingerprint", "public_key" ], "type": "object", "properties": { "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The signing key's version (1 at creation; higher after rotation).", "format": "int32" }, "created_at": { "type": "string", "description": "When this key version was created.", "format": "date-time", "example": "2026-06-08T12:00:00+00:00" }, "fingerprint": { "type": "string", "description": "Lowercase hex SHA-256 of the public key, to recognize it.", "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "public_key": { "type": "string", "description": "The raw 32-byte Ed25519 public key, base64-encoded." } }, "description": "One of an organization's signing keys, with its raw public key material, so an\noperator can hand the public key to the organization (for example during\nonboarding, or to help an integrator not yet driving the API). The private key\nnever leaves Vault. Verifiers that drive the API resolve keys from the Data\nAPI's JWKS instead." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ProvisionEmitterRequest": { "required": [ "emitter_id", "name", "cert" ], "type": "object", "properties": { "emitter_id": { "type": "string", "description": "The emitter's opaque identifier. Required, non-empty, unique." }, "name": { "type": "string", "description": "The emitter's display name. Required, non-empty." }, "description": { "type": [ "null", "string" ], "description": "Operator-facing context for the emitter. Optional." }, "privileged": { "type": "boolean", "description": "Whether this emitter may write reserved chains, such as the system chain.\nDefaults to `false`; reserved-chain authorization is granted explicitly." }, "cert": { "description": "The cert-provisioning mode (caller CSR or platform-generated keypair).", "$ref": "#/components/schemas/EmitterCertRequest" } }, "description": "Request to provision an emitter: issue its mTLS cert and insert its registry\nrow, atomically. The new row is operator-managed." }, "RevokeCredentialRequest": { "type": "object", "properties": { "reason": { "type": [ "null", "string" ], "description": "Why the credential is being revoked. Optional.", "example": "key suspected compromised" } }, "description": "Request body to revoke a credential. The `reason` is optional; when given\nit is recorded on the credential and carried on the audit event." }, "RevokeEmitterRequest": { "type": "object", "properties": { "reason": { "type": [ "null", "string" ], "description": "Why the emitter is being revoked. Optional.", "example": "cert suspected compromised" } }, "description": "Request body to revoke an emitter. The `reason` is optional; when given it\nis carried on the audit event recording the revocation." }, "RotateCredentialRequest": { "type": "object", "properties": { "expires_at": { "type": [ "null", "string" ], "description": "The credential's new expiry, when renewing. Optional; must be in the future.", "format": "date-time", "example": "2027-01-01T00:00:00+00:00" } }, "description": "Optional request body to rotate a credential. `expires_at` renews the\ncredential at the same time as rotating it: omit it to keep the current expiry,\nor set it (must be in the future) to reschedule. The body itself is optional; a\nrotate with no body keeps the expiry." }, "SupportSession": { "required": [ "support_session_id", "organization_id", "operator_subject", "operator_name", "reason", "ticket_reference", "opened_at", "expires_at" ], "type": "object", "properties": { "support_session_id": { "type": "string", "description": "Identifier of the session.", "format": "uuid" }, "organization_id": { "type": "string", "description": "The organization the session grants a view of.", "format": "uuid" }, "operator_subject": { "type": "string", "description": "The operator (OIDC subject) the session was opened for." }, "operator_name": { "type": [ "null", "string" ], "description": "The operator's display name at open time, or `null` when the issuer supplied none." }, "reason": { "type": "string", "description": "The operator's declared reason (a free-text audit annotation)." }, "ticket_reference": { "type": "string", "description": "The support ticket the session was opened against." }, "opened_at": { "type": "string", "description": "When the session was opened.", "format": "date-time" }, "expires_at": { "type": "string", "description": "When the grant expires and the session auto-closes.", "format": "date-time" } }, "description": "An active support session as listed/fetched by an operator (the wire resource)." }, "SupportSessionGrant": { "required": [ "redirect_url", "expires_at" ], "type": "object", "properties": { "redirect_url": { "type": "string", "description": "The Data Viewer support-grant handoff to redirect the browser to." }, "expires_at": { "type": "string", "description": "When the grant expires and the session auto-closes.", "format": "date-time" } }, "description": "The grant issued when a support session is opened or resumed: the one-time Data\nViewer handoff that carries the grant token, and when the grant expires. The\ngrant is returned only at issuance, mirroring how credential issuance returns a\none-time secret." }, "SupportSessionResponse": { "required": [ "session", "grant" ], "type": "object", "properties": { "session": { "description": "The session (the same shape the list/get return).", "$ref": "#/components/schemas/SupportSession" }, "grant": { "description": "The grant issued for the session: the one-time Data Viewer handoff and its expiry.", "$ref": "#/components/schemas/SupportSessionGrant" } }, "description": "The response to opening or resuming a support session: the session resource and\nthe grant issued for it." }, "Tenant": { "required": [ "tenant_id", "display_name", "onboarded_at" ], "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Opaque tenant identifier, used as the `tenant_id` on the event surfaces.", "example": "acme-eu" }, "display_name": { "type": "string", "description": "Human-readable tenant name.", "example": "Acme Europe" }, "onboarded_at": { "type": "string", "description": "When the tenant was onboarded (ISO 8601).", "format": "date-time", "example": "2026-01-15T09:30:00+00:00" } }, "description": "A tenant of an organization: a sub-scope with its own opaque id, display name,\nand chain. The owning organization is the one in the route, so it is not\nrepeated here." }, "TenantOverview": { "required": [ "tenant_id", "display_name", "onboarded_at", "activity", "signing_key", "packs" ], "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Opaque tenant identifier.", "example": "acme-eu" }, "display_name": { "type": "string", "description": "Human-readable tenant name.", "example": "Acme Europe" }, "onboarded_at": { "type": "string", "description": "When the tenant was onboarded (ISO 8601).", "format": "date-time", "example": "2026-01-15T09:30:00+00:00" }, "activity": { "description": "Chain volume and recency, plus the event types the tenant carries.", "$ref": "#/components/schemas/TenantOverviewActivity" }, "signing_key": { "description": "The signing-key version the chain head was signed under, against the current version.", "$ref": "#/components/schemas/TenantOverviewSigningKey" }, "packs": { "description": "The tenant's data-pack figures.", "$ref": "#/components/schemas/TenantOverviewPacks" } }, "description": "An operator's read-only view of a tenant's operational state: its identity and\nthree grouped facets, namely chain activity, the signing-key version its head was\nsigned under against the organization's current version, and its data-pack\nfigures. This describes the chain, not its contents; no event payload is exposed." }, "TenantOverviewActivity": { "required": [ "event_count", "events_last_24h", "events_last_7d", "events_last_30d", "event_names" ], "type": "object", "properties": { "event_count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total events on the tenant's chain.", "format": "int64" }, "events_last_24h": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Events ingested in the last 24 hours (by `receipt_ts`).", "format": "int64" }, "events_last_7d": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Events ingested in the last 7 days (by `receipt_ts`).", "format": "int64" }, "events_last_30d": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Events ingested in the last 30 days (by `receipt_ts`).", "format": "int64" }, "last_event": { "oneOf": [ { "type": "null" }, { "description": "The tenant's most recent event, or `null` when the chain is empty.", "$ref": "#/components/schemas/TenantOverviewLastEvent" } ] }, "event_names": { "type": "array", "items": { "type": "string" }, "description": "The distinct event names present on the chain, ordered alphabetically." } }, "description": "A tenant's chain activity: how much is on the chain and how recently, plus the\ndistinct event types it carries. The recent windows count by ingestion time." }, "TenantOverviewLastEvent": { "required": [ "event_name", "date", "receipt_ts" ], "type": "object", "properties": { "event_name": { "type": "string", "description": "The event name (versioned).", "example": "qaudit.tenant.updated.v1" }, "date": { "type": "string", "description": "The business date the emitter asserted (ISO 8601).", "format": "date-time", "example": "2026-06-12T14:05:00+00:00" }, "receipt_ts": { "type": "string", "description": "When the Gateway ingested the event (ISO 8601).", "format": "date-time", "example": "2026-06-12T14:05:01+00:00" } }, "description": "The tenant's chain head: its name and its two timestamps." }, "TenantOverviewPacks": { "required": [ "total", "building", "ready", "failed" ], "type": "object", "properties": { "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Packs whose resolved chain is this tenant.", "format": "int64" }, "building": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Packs still building.", "format": "int64" }, "ready": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Packs that finished building.", "format": "int64" }, "failed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Packs whose build failed.", "format": "int64" }, "last_built_at": { "type": [ "null", "string" ], "description": "When the most recent ready pack finished building, or `null` when none is ready.", "format": "date-time" } }, "description": "The tenant's data-pack figures: the total, the per-status split, and the last build time." }, "TenantOverviewSigningKey": { "type": "object", "properties": { "head_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The version the chain head was signed under, or `null` when the chain is empty.", "format": "int32" }, "current_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "The organization's current (highest) signing-key version, or `null` when it has no keys.", "format": "int32" } }, "description": "The signing-key versions for the tenant: the version its chain head was signed\nunder, against the organization's current version. A head version below the\ncurrent one marks a chain whose head predates a key rotation." }, "TenantPage": { "required": [ "items", "total", "page", "page_size" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" }, "description": "The tenants on this page, ordered by display name." }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total tenants across all pages.", "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The 1-based page number.", "format": "int32" }, "page_size": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The page size applied.", "format": "int32" } }, "description": "One page of an organization's tenants: the rows plus the total count so a\ncaller can render page numbers." }, "UpdateEmitterRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The emitter's display name after the edit. Required, non-empty." }, "description": { "type": [ "null", "string" ], "description": "The emitter's description after the edit, or `null` to clear it." } }, "description": "Request to edit an emitter's name and description. Cert rotation is a separate\noperation (`POST /system/emitters/{emitter_id}/cert`)." }, "UpdateOrganizationRequest": { "type": "object", "properties": { "display_name": { "type": [ "null", "string" ], "description": "The organization's new display name, shown wherever the organization is identified." } }, "description": "Request to edit an organization. Currently the display name is the only editable field." }, "UpdateTenantRequest": { "type": "object", "properties": { "display_name": { "type": [ "null", "string" ], "description": "The tenant's new display name. Required, non-empty." } }, "description": "Request to edit a tenant's display name." } }, "securitySchemes": { "OidcSession": { "type": "http", "description": "Operator session: an OIDC access token from the Admin API's configured identity provider, presented as `Authorization: Bearer `. Relayed by the Web Gateway from the operator's session; any user the provider authenticates is an operator.", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKey": { "type": "http", "description": "Admin-capable system API key, presented as `Authorization: Bearer `. Issued by the `/system/credentials` surface with the `admin` capability.", "scheme": "bearer" } } }, "security": [ { "OidcSession": [ ] }, { "ApiKey": [ ] } ], "tags": [ { "name": "Organizations", "description": "Organizations: the identity, credential, and signing boundary that tenants live inside. Each carries a display name and a per-organization Ed25519 signing key (provisioned at creation). Creating an organization provisions its signing key and opens its access-trail chain; tenants are added separately. An organization's signing keys are read through its signing-keys endpoint." }, { "name": "Tenants", "description": "Tenants: the sub-scopes within an organization, each with its own opaque id, display name, and access-trail chain. Adding a tenant opens its chain (whose first event is `qaudit.tenant.created.v1`); editing one is audited on the tenant's own chain." }, { "name": "Organization credentials", "description": "Credentials scoped to a single organization. An organization credential is **data-only** by definition: it grants read access to its organization's data. The secret is shown once, at issuance or rotation, and is stored only as a hash. Every mutation (issue, rotate, revoke) is audited on the organization's own chain." }, { "name": "Admin API credentials", "description": "Credentials bound to no single organization, carrying an `admin` access level (`read-only` or `read-write`) that grants Admin API access to manage the platform. An Admin API credential reaches the Admin API only; it has no data-read access. The secret is shown once and is stored only as a hash. Every mutation is audited on the system chain." }, { "name": "Emitters", "description": "Emitters: the applications authenticated to submit events to QAudit, each holding an mTLS client cert and a registry row. An emitter is a root, system-scoped resource bound to no single organization. Provisioning issues the cert in one of two modes: supply a `csr` to have it signed (the private key never leaves the caller), or omit it to receive a platform-generated PKCS#12 bundle. Platform-managed rows (the platform's own internal emitters) are listed but read-only: mutating one responds `403`. Every mutation is audited on the system chain." }, { "name": "Support sessions", "description": "Support sessions: how a Quadient operator views one organization's data. Opening a session mints a short-lived, scope-bound grant for the operator and returns a redirect to the Data Viewer at that organization. A session is time-bound: it auto-closes when the grant expires, with no explicit close. Both the opening and the closing are audited on the organization's chain (`qaudit.support.session.opened.v1` / `qaudit.support.session.closed.v1`)." } ], "externalDocs": { "description": "Operating QAudit: organization, credential, emitter, and support-session procedures.", "url": "https://support.nightly.qaudit.ismailbennani.fr" } }