{ "openapi": "3.1.0", "info": { "title": "DAJU Verify API", "version": "1.0.0", "description": "Implemented foundation for creating and retrieving verification sessions and consuming signed verification outcome webhooks. API keys are application- and environment-bound. Session creation, workflow listing, session listing, and verification-result reads are sandbox-only in this phase." }, "servers": [ { "url": "https://daju-mocha.vercel.app/api/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "/workflows": { "get": { "operationId": "listPublishedWorkflows", "summary": "List published sandbox workflows", "description": "Returns only active, published workflows for the API key's application.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A bounded page of published workflows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedWorkflowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/verification-sessions": { "get": { "operationId": "listVerificationSessions", "summary": "List sandbox verification sessions", "description": "Sandbox-only in this phase. Live credentials fail closed.", "description": "Returns a bounded, tenant- and application-scoped page without external references or identity data.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/SessionStatus" }, { "$ref": "#/components/parameters/CreatedAfter" }, { "$ref": "#/components/parameters/CreatedBefore" } ], "responses": { "200": { "description": "A bounded page of safe verification-session metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSessionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createVerificationSession", "summary": "Create a verification session", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVerificationSession" } } } }, "responses": { "201": { "description": "Session created. hostedUrl is returned only on creation.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedVerificationSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/verification-sessions/{id}": { "get": { "operationId": "getVerificationSession", "summary": "Retrieve a verification session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tenant- and environment-scoped session metadata.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/verifications/{id}": { "get": { "operationId": "getVerificationResult", "summary": "Retrieve a safe sandbox verification result", "description": "Sandbox-only in this phase. Live credentials fail closed.", "description": "Returns decision status and normalized risk/trust bands only. Evidence, identity claims, provider payloads, subject identifiers, and raw scores are never included.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A tenant- and application-scoped safe verification result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "webhooks": { "verificationOutcome": { "post": { "operationId": "receiveVerificationOutcome", "summary": "Receive a signed verification outcome", "description": "DAJU sends only the events selected for the endpoint. verification.retry_required, verification.inconclusive, and verification.review_required are non-approval outcomes.", "security": [], "parameters": [ { "name": "X-DAJU-Signature", "in": "header", "required": true, "description": "HMAC-SHA-256 signature in v1= format.", "schema": { "type": "string", "pattern": "^v1=[a-f0-9]{64}$" } }, { "name": "X-DAJU-Timestamp", "in": "header", "required": true, "description": "UTC timestamp included in the signed payload input. Reject stale deliveries.", "schema": { "type": "string", "format": "date-time" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationWebhookEvent" } } } }, "responses": { "200": { "description": "The event receipt and related product state change committed atomically. Duplicate event IDs may return the same success response." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "DAJU API key", "description": "Use a server-side DAJU API key. Session creation and the new list/result operations are sandbox-only in this phase; live use is supported only where an operation explicitly says so." } }, "parameters": { "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page. It is bound to the resource and active filters.", "schema": { "type": "string", "minLength": 20, "maxLength": 600 } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "SessionStatus": { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/VerificationSessionStatus" } }, "CreatedAfter": { "name": "createdAfter", "in": "query", "required": false, "description": "Inclusive canonical UTC timestamp.", "schema": { "type": "string", "format": "date-time" } }, "CreatedBefore": { "name": "createdBefore", "in": "query", "required": false, "description": "Exclusive canonical UTC timestamp. When both bounds are supplied, the interval cannot exceed 366 days.", "schema": { "type": "string", "format": "date-time" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 160 }, "description": "Reuse only when retrying the identical create request." } }, "headers": { "CorrelationId": { "description": "Request correlation identifier.", "schema": { "type": "string", "format": "uuid" } }, "RateLimitLimit": { "description": "Maximum authenticated requests in the current window.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitReset": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer", "minimum": 0 } } }, "schemas": { "CreateVerificationSession": { "type": "object", "additionalProperties": false, "required": [ "workflowId" ], "properties": { "workflowId": { "type": "string", "format": "uuid" }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 160 }, "hostedReturnUrl": { "type": "string", "format": "uri", "pattern": "^https://[^\\s@/?#]+(?:/[^\\s?#]*)?$", "minLength": 1, "maxLength": 1000, "description": "Optional exact HTTPS destination selected from the application's configured allowlist. Credentials, query strings, and fragments are forbidden. DAJU does not append a token, status, result, or evidence." } } }, "CreatedVerificationSession": { "type": "object", "additionalProperties": false, "required": [ "id", "environment", "status", "hostedUrl", "hostedReturnUrl", "expiresAt", "correlationId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "status": { "$ref": "#/components/schemas/VerificationSessionStatus" }, "hostedUrl": { "type": "string", "format": "uri", "description": "One-time hosted-session URL." }, "hostedReturnUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Exact database-bound hostedReturnUrl snapshot selected for this session, or null. It contains no appended token, status, result, or evidence." }, "expiresAt": { "type": "string", "format": "date-time" }, "correlationId": { "type": "string", "format": "uuid" } } }, "VerificationSession": { "type": "object", "additionalProperties": false, "required": [ "id", "workflowId", "workflowVersionId", "targetAssuranceLevel", "status", "expiresAt", "createdAt", "correlationId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workflowId": { "type": "string", "format": "uuid" }, "workflowVersionId": { "type": "string", "format": "uuid" }, "targetAssuranceLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "status": { "$ref": "#/components/schemas/VerificationSessionStatus" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "correlationId": { "type": "string", "format": "uuid" } } }, "VerificationSessionStatus": { "type": "string", "enum": [ "created", "in_progress", "pending", "completed", "passed", "failed", "inconclusive", "retry_required", "manual_review", "cancelled", "expired" ] }, "PageMetadata": { "type": "object", "additionalProperties": false, "required": [ "hasMore", "nextCursor" ], "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "PublishedWorkflow": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "versionId", "version", "targetAssuranceLevel", "publishedAt", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "versionId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "targetAssuranceLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "publishedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "PublishedWorkflowPage": { "type": "object", "additionalProperties": false, "required": [ "correlationId", "data", "pagination" ], "properties": { "correlationId": { "type": "string", "format": "uuid" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublishedWorkflow" } }, "pagination": { "$ref": "#/components/schemas/PageMetadata" } } }, "VerificationSessionSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "workflowId", "workflowVersionId", "targetAssuranceLevel", "status", "startedAt", "completedAt", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workflowId": { "type": "string", "format": "uuid" }, "workflowVersionId": { "type": "string", "format": "uuid" }, "targetAssuranceLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "status": { "$ref": "#/components/schemas/VerificationSessionStatus" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "VerificationSessionPage": { "type": "object", "additionalProperties": false, "required": [ "correlationId", "data", "pagination" ], "properties": { "correlationId": { "type": "string", "format": "uuid" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationSessionSummary" } }, "pagination": { "$ref": "#/components/schemas/PageMetadata" } } }, "VerificationResult": { "type": "object", "additionalProperties": false, "required": [ "id", "workflowId", "workflowVersionId", "targetAssuranceLevel", "status", "decision", "decisionSource", "resultState", "riskBand", "trustBand", "reviewState", "manualReviewRequired", "reverificationRequired", "decidedAt", "finalizedAt", "completedAt", "createdAt", "correlationId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workflowId": { "type": "string", "format": "uuid" }, "workflowVersionId": { "type": "string", "format": "uuid" }, "targetAssuranceLevel": { "type": "integer", "minimum": 0, "maximum": 4 }, "status": { "$ref": "#/components/schemas/VerificationSessionStatus" }, "decision": { "type": [ "string", "null" ], "enum": [ "approved", "approved_with_conditions", "manual_review", "retry_required", "rejected", "inconclusive", "expired", "cancelled", null ] }, "decisionSource": { "type": [ "string", "null" ], "enum": [ "automated", "manual_review", "appeal", null ], "description": "The authority that produced the effective finalized decision." }, "resultState": { "type": "string", "enum": [ "pending_review", "awaiting_countersign", "final", "under_appeal" ], "description": "Whether the effective decision is final or a review workflow is still active." }, "riskBand": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "critical", null ] }, "trustBand": { "type": [ "string", "null" ], "enum": [ "low", "moderate", "substantial", "high", null ] }, "reviewState": { "type": [ "string", "null" ], "enum": [ "queued", "assigned", "in_review", "escalated", "pending_secondary", "decided", "qa_pending", "appealed", "closed", "expired", "cancelled", null ] }, "manualReviewRequired": { "type": [ "boolean", "null" ] }, "reverificationRequired": { "type": [ "boolean", "null" ] }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finalizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "correlationId": { "type": "string", "format": "uuid" } } }, "VerificationWebhookEvent": { "oneOf": [ { "$ref": "#/components/schemas/VerificationCompletedWebhookEvent" }, { "$ref": "#/components/schemas/VerificationFailedWebhookEvent" }, { "$ref": "#/components/schemas/VerificationReviewRequiredWebhookEvent" }, { "$ref": "#/components/schemas/VerificationRetryRequiredWebhookEvent" }, { "$ref": "#/components/schemas/VerificationInconclusiveWebhookEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "verification.completed": "#/components/schemas/VerificationCompletedWebhookEvent", "verification.failed": "#/components/schemas/VerificationFailedWebhookEvent", "verification.review_required": "#/components/schemas/VerificationReviewRequiredWebhookEvent", "verification.retry_required": "#/components/schemas/VerificationRetryRequiredWebhookEvent", "verification.inconclusive": "#/components/schemas/VerificationInconclusiveWebhookEvent" } } }, "VerificationCompletedWebhookEvent": { "type": "object", "additionalProperties": false, "required": ["id", "type", "created_at", "data"], "properties": { "id": { "type": "string", "pattern": "^evt_[a-zA-Z0-9_]+$", "description": "Stable event identifier used for idempotent receipt storage." }, "type": { "const": "verification.completed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "required": ["verification_session_id", "status", "risk_level", "decision"], "properties": { "verification_session_id": { "type": "string", "format": "uuid" }, "status": { "const": "passed" }, "risk_level": { "type": "string" }, "decision": { "type": "string", "enum": ["approved", "approved_with_conditions"] } } } } }, "VerificationFailedWebhookEvent": { "type": "object", "additionalProperties": false, "required": ["id", "type", "created_at", "data"], "properties": { "id": { "type": "string", "pattern": "^evt_[a-zA-Z0-9_]+$", "description": "Stable event identifier used for idempotent receipt storage." }, "type": { "const": "verification.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "required": ["verification_session_id", "status", "risk_level", "decision"], "properties": { "verification_session_id": { "type": "string", "format": "uuid" }, "status": { "const": "failed" }, "risk_level": { "type": "string" }, "decision": { "const": "rejected" } } } } }, "VerificationReviewRequiredWebhookEvent": { "type": "object", "additionalProperties": false, "required": ["id", "type", "created_at", "data"], "properties": { "id": { "type": "string", "pattern": "^evt_[a-zA-Z0-9_]+$", "description": "Stable event identifier used for idempotent receipt storage." }, "type": { "const": "verification.review_required" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "required": ["verification_session_id", "status", "risk_level", "decision"], "properties": { "verification_session_id": { "type": "string", "format": "uuid" }, "status": { "const": "manual_review" }, "risk_level": { "type": "string" }, "decision": { "const": "manual_review" } } } } }, "VerificationRetryRequiredWebhookEvent": { "type": "object", "additionalProperties": false, "required": ["id", "type", "created_at", "data"], "properties": { "id": { "type": "string", "pattern": "^evt_[a-zA-Z0-9_]+$", "description": "Stable event identifier used for idempotent receipt storage." }, "type": { "const": "verification.retry_required" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "required": ["verification_session_id", "status", "risk_level", "decision"], "properties": { "verification_session_id": { "type": "string", "format": "uuid" }, "status": { "const": "retry_required" }, "risk_level": { "type": "string" }, "decision": { "const": "retry_required" } } } } }, "VerificationInconclusiveWebhookEvent": { "type": "object", "additionalProperties": false, "required": ["id", "type", "created_at", "data"], "properties": { "id": { "type": "string", "pattern": "^evt_[a-zA-Z0-9_]+$", "description": "Stable event identifier used for idempotent receipt storage." }, "type": { "const": "verification.inconclusive" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "required": ["verification_session_id", "status", "risk_level", "decision"], "properties": { "verification_session_id": { "type": "string", "format": "uuid" }, "status": { "const": "inconclusive" }, "risk_level": { "type": "string" }, "decision": { "const": "inconclusive" } } } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "BadRequest": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorised": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key cannot access this resource or environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "Payload exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnsupportedMediaType": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "The authenticated API-key request limit was exceeded.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }