openapi: 3.2.0 info: title: Axonflow Audit Verification API version: 11.1.0 contact: name: AxonFlow Support url: https://getaxonflow.com/support license: name: Business Source License 1.1 url: https://github.com/getaxonflow/axonflow/blob/main/LICENSE description: 'Operations tagged Audit Verification across 2 of this provider''s published API definitions: axonflow-agent-api.yaml, axonflow-agent-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development tags: - name: Audit Verification description: Non-repudiation verification of the signed decision chain (#2722). paths: /api/v1/audit/chains/{chainID}/verify: get: tags: - Audit Verification summary: Verify a decision chain description: 'Re-verifies an entire decision chain: the `prev_hash` linkage across all of its records (ordering / completeness) and every per-record Ed25519 signature (authorship). Read-only; never mutates the chain. The chain is resolved by id **only within the authenticated caller''s organization** (RLS-scoped); the org is taken from the request credentials, never from a path or query parameter. `chainID` is the decision id (a UUID). Inspect `authorship_proven` for the strong non-repudiation claim (every record signed and all signatures + linkage verify). `valid` only means no integrity violation was detected and can be `true` for a chain with zero signed records, so do not gate non-repudiation on `valid` alone. **Authority (#2914).** Authentication alone is not enough: this route requires COMPLIANCE READ AUTHORITY over the organization. Present a validated per-user token (`X-User-Token`, or `Authorization: Bearer`) whose role is `admin`, `owner` or `policy_admin`, or call from an internal service asserting `X-Axonflow-Admin-Authority: true`. A Community-mode deployment is exempt: it has no authentication and resolves every caller to one local operator. Anything else is `403`. **Community SaaS (`try.getaxonflow.com`) refuses these routes, by design.** The hosted evaluation stack runs with authentication enabled, so the Community-mode exemption above does not apply to it, and its evaluator accounts hold no entitled role. Verification there is a `403`. Granting evaluators access would widen, on a public shared stack, the exact exposure this change closes. Verify audit records on a deployment you operate.' operationId: verifyAuditChain parameters: - $ref: '#/components/parameters/LicenseKey' - name: chainID in: path required: true description: Decision chain id (the decision UUID) schema: type: string format: uuid responses: '200': description: Verification result (the chain exists in your organization) content: application/json: schema: $ref: '#/components/schemas/ChainVerificationResult' '400': description: chainID is not a valid UUID content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '401': description: Missing authenticated org context content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '403': description: 'Authenticated, but without compliance read authority over this organization (#2914). See the authority note in the description. ' content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '404': description: No decision chain found for this id in your organization content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '500': description: Verification failed (internal error) content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/audit/records/{recordID}/verify: get: tags: - Audit Verification summary: Verify a single decision record description: 'Verifies ONE decision record standalone, proving its authorship from the record alone without walking the rest of the chain. Read-only. The response republishes the recomputed verification material so the result is independently checkable offline: `digest_preimage_b64` is the exact byte string that SHA-256-hashes to `record_digest`; an auditor can base64-decode it, hash it, confirm it equals `record_digest`, rebuild it from the raw record fields, and then run `ed25519.Verify(public_key, []byte(chain_hash), base64decode(record_signature))`, trusting neither this endpoint nor its digest. The record is resolved by id only within the authenticated caller''s organization (RLS-scoped). `recordID` is the per-record UUID assigned at signing time (distinct from the chain id). **Authority (#2914).** Authentication alone is not enough: this route requires COMPLIANCE READ AUTHORITY over the organization. Present a validated per-user token (`X-User-Token`, or `Authorization: Bearer`) whose role is `admin`, `owner` or `policy_admin`, or call from an internal service asserting `X-Axonflow-Admin-Authority: true`. A Community-mode deployment is exempt: it has no authentication and resolves every caller to one local operator. Anything else is `403`. **Community SaaS (`try.getaxonflow.com`) refuses these routes, by design.** The hosted evaluation stack runs with authentication enabled, so the Community-mode exemption above does not apply to it, and its evaluator accounts hold no entitled role. Verification there is a `403`. Granting evaluators access would widen, on a public shared stack, the exact exposure this change closes. Verify audit records on a deployment you operate.' operationId: verifyAuditRecord parameters: - $ref: '#/components/parameters/LicenseKey' - name: recordID in: path required: true description: Decision record id (the per-record UUID) schema: type: string format: uuid responses: '200': description: Verification result (the record exists in your organization) content: application/json: schema: $ref: '#/components/schemas/RecordVerificationResult' '400': description: recordID is not a valid UUID content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '401': description: Missing authenticated org context content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '403': description: 'Authenticated, but without compliance read authority over this organization (#2914). See the authority note in the description. ' content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '404': description: No decision record found for this id in your organization content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '500': description: Verification failed (internal error) content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/audit/signing-key: get: tags: - Audit Verification summary: Publish the current public signing key description: 'Returns the current public Ed25519 verification key so an external auditor can re-verify any record''s signature offline. Read-only. When no signing key is configured, `configured` is `false` and `public_key` is empty: records are hash-chained but unsigned, and the verify endpoints report that honestly. **Authority (#2914).** Authentication alone is not enough: this route requires COMPLIANCE READ AUTHORITY over the organization. Present a validated per-user token (`X-User-Token`, or `Authorization: Bearer`) whose role is `admin`, `owner` or `policy_admin`, or call from an internal service asserting `X-Axonflow-Admin-Authority: true`. A Community-mode deployment is exempt: it has no authentication and resolves every caller to one local operator. Anything else is `403`. **Community SaaS (`try.getaxonflow.com`) refuses these routes, by design.** The hosted evaluation stack runs with authentication enabled, so the Community-mode exemption above does not apply to it, and its evaluator accounts hold no entitled role. Verification there is a `403`. Granting evaluators access would widen, on a public shared stack, the exact exposure this change closes. Verify audit records on a deployment you operate.' operationId: getAuditSigningKey parameters: - $ref: '#/components/parameters/LicenseKey' responses: '200': description: Current public signing key (or that none is configured) content: application/json: schema: $ref: '#/components/schemas/AuditSigningKeyResponse' '401': description: Missing authenticated org context content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' '403': description: 'Authenticated, but without compliance read authority over this organization (#2914). See the authority note in the description. ' content: application/json: schema: $ref: '#/components/schemas/AuditVerifyError' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development components: schemas: AuditVerifyError: type: object description: Error envelope returned by the audit-verification endpoints. properties: error: type: string description: Human-readable error message. required: - error ChainVerificationResult: type: object description: 'Outcome of verifying an entire decision chain''s prev_hash linkage and every per-record Ed25519 signature. ' properties: chain_id: type: string format: uuid org_id: type: string total_records: type: integer valid: type: boolean description: 'True when no integrity violation was detected (linkage holds and every signature that exists verifies). Can be true for a chain with zero signed records. Use `authorship_proven` for the strong claim. ' authorship_proven: type: boolean description: 'True only when every record is signed AND all signatures + linkage verify. Gate non-repudiation on this flag. ' linkage_valid: type: boolean signatures_valid: type: boolean signed_records: type: integer unsigned_records: type: integer first_broken_seq: type: integer format: int64 description: Sequence of the first detected break (omitted when valid). first_broken_record_id: type: string description: Record id of the first detected break (omitted when valid). break_reason: type: string description: Why the chain broke (omitted when valid). signing_key_id: type: string description: Identifier of the tracker's current signing key. public_key: type: string description: Base64 Ed25519 public key for offline re-verification. verified_at: type: string format: date-time required: - chain_id - org_id - total_records - valid - authorship_proven - linkage_valid - signatures_valid - verified_at AuditSigningKeyResponse: type: object description: The current public Ed25519 verification key (or that none is configured). properties: algorithm: type: string example: ed25519 signing_key_id: type: string description: Identifier of the current signing key (empty when none configured). public_key: type: string description: Base64 Ed25519 public key (empty when none configured). configured: type: boolean description: False when no signing key is configured (records are hash-chained but unsigned). verification_note: type: string description: How to verify a record offline with this key. required: - algorithm - configured RecordVerificationResult: type: object description: 'Outcome of verifying a SINGLE decision record standalone. Republishes the recomputed material so the result is independently checkable offline. ' properties: record_id: type: string format: uuid chain_id: type: string format: uuid org_id: type: string chain_seq: type: integer format: int64 signed: type: boolean signature_valid: type: boolean valid: type: boolean reason: type: string description: Explanation when the record does not verify (omitted when valid). digest_preimage_b64: type: string description: 'Base64 of the exact byte string that SHA-256-hashes to `record_digest`. Decode, hash, and confirm it equals `record_digest`, then rebuild it from the raw record fields to verify independently. ' record_digest: type: string description: SHA-256 hex of the record pre-image. prev_hash: type: string description: Hash of the previous record in the chain. chain_hash: type: string description: 'sha256_hex(record_digest + "|" + prev_hash); the message that the Ed25519 signature is computed over. ' record_signature: type: string description: Base64 Ed25519 signature over `chain_hash` (omitted when unsigned). signing_key_id: type: string public_key: type: string description: Base64 Ed25519 public key for offline re-verification. verified_at: type: string format: date-time required: - record_id - chain_id - org_id - chain_seq - signed - signature_valid - valid - digest_preimage_b64 - record_digest - prev_hash - chain_hash - verified_at parameters: LicenseKey: name: Authorization in: header required: true description: 'OAuth2-style Basic authentication header. Format: `Basic base64(clientId:clientSecret)` - `clientId`: Your organization identifier (required) - `clientSecret`: Authentication credential (optional for community mode) Not required when `DEPLOYMENT_MODE=community`. ' schema: type: string example: Basic bXktb3JnOkFYT04tVjIteHh4 securitySchemes: BasicAuth: type: http scheme: basic description: "OAuth2-style Basic authentication using `clientId:clientSecret` credentials.\n\n**Header format:** `Authorization: Basic base64(clientId:clientSecret)`\n\n- `clientId` (required): Your organization/client identifier\n- `clientSecret` (optional): Authentication credential. Optional for community/self-hosted mode.\n\n**Example:**\n```bash\n# With clientSecret (enterprise)\ncurl -H \"Authorization: Basic $(echo -n 'my-org:AXON-V2-xxx' | base64)\" ...\n\n# Without clientSecret (community mode)\ncurl -H \"Authorization: Basic $(echo -n 'my-org:' | base64)\" ...\n```\n\n## Per-user identity behind a shared credential\n\nThis credential authenticates an ORGANIZATION or client, not a person.\nBehind one such credential can sit many human principals, each\noptionally forwarding a **per-user token** that proves who they are.\nWhere that token is read depends on the envelope: the `user_token`\nfield of the request body on `POST /api/v1/decide` and the four MCP\nREST routes, and the `X-User-Token` header on the MCP-server JSON-RPC\nplane. The two spellings are deliberately not interchangeable.\n\n**A presented per-user token that fails to validate is a refused\naccess attempt, not a legacy caller** (`401`, audited\n`user_token_rejected`). It is never downgraded to a shared service\nidentity, so revocation, expiry, algorithm pinning and signature\nchecks take effect on every plane that reads one.\n\n**Whether presenting a token is REQUIRED is a per-organization\nposture, `require_user_token`, and it is off by default (#3476).**\nWith it off, an enterprise caller that presents no token at all is\nserved under a synthetic org-scoped service identity\n(`@axonflow.local`, role `service`), which is the correct\nanswer for an infrastructure gateway acting as a Policy Enforcement\nPoint with no end-user token to forward. With it on, that caller is\nrefused at AUTHENTICATION, before any policy is evaluated (`401`,\naudited `user_token_required`).\n\nThe posture exists because a policy that names a PERSON - a\nprincipal-scoped constraint or permission in the organization's typed\ndocument (PRD v11 §1.6) - is only meaningful if a caller cannot CHOOSE\nto arrive without an identity: with the posture off such a policy\nstill applies to everyone who presents a token, but a caller can\ndecline to present one and be decided as the credential\n(`subject_type=Client`). Governance segments (ADR-060) decide on no\nagent route since v11.0.0 (#4253). Two levers set it, and an explicit\nper-organization row wins over the deployment-wide default in EITHER\ndirection:\n\n- `organizations.require_user_token`, per organization, default\n `false`.\n- `AXONFLOW_REQUIRE_USER_TOKEN`, deployment-wide, default `false`.\n\nA posture change takes up to one cache window to become live\n(`AXONFLOW_REQUIRE_USER_TOKEN_TTL_SECONDS`, default 60 seconds,\nclamped to `[5, 600]`). A posture that cannot be READ resolves to\nREQUIRED rather than not-required, so a database outage cannot\nquietly switch the control off; a genuinely absent organization row\nis not a read failure and falls through to the deployment default.\n\n`POST /v1/chat/completions` is outside this guarantee: it mirrors\nOpenAI's wire shape and carries no per-user token field at all, so it\nkeeps the synthetic-identity fallback regardless of the posture.\nCommunity and community-SaaS deployments never reach any of the above.\n" InternalServiceID: type: apiKey in: header name: X-Internal-Service-ID description: 'Internal-service (operator lane) credential — **part one of two**. Must be sent together with `X-Internal-Service-Token`; either header alone is not a credential. This is the HMAC identity the Orchestrator and the Enterprise customer-portal use to call agent endpoints without holding a customer license. `apiAuthMiddleware` lifts both headers (plus an optional `X-Tenant-ID` scope) into `AuthHints` (`internalServiceHints` in `platform/agent/auth.go`) and `Authenticate()` validates them before any mode-specific auth (`platform/agent/authenticator.go:120-155`). Value: the service id, `orchestrator-internal`. ⚠️ An invalid or expired token is **not** an error by itself — it falls through to the deployment''s normal auth (`platform/agent/authenticator.go:153-154`). Send the internal-service headers on their own: paired with an `Authorization: Basic` header, a stale token silently yields a *tenant*-scoped answer that looks like a successful operator call. ' InternalServiceToken: type: apiKey in: header name: X-Internal-Service-Token description: 'Internal-service (operator lane) credential — **part two of two**. Must be sent together with `X-Internal-Service-ID`. Format: `AXON-INTERNAL-{unix_ts}-{sig}`, where `sig` is the first 16 hex characters of HMAC-SHA256 over `orchestrator-internal:{unix_ts}` keyed with `AXONFLOW_INTERNAL_SERVICE_SECRET`. Validated by `platform/shared/serviceauth` within a 5-minute clock-skew window, so it must be re-minted per session. See `technical-docs/runbooks/RUNBOOK_CONNECTOR_CONFIGURATION.md` for the exact minting snippet. ' x-refined-from: - axonflow-agent-api.yaml - axonflow-agent-openapi.yml