{ "openapi": "3.1.1", "info": { "title": "Trusted Palm ID - Target Integration Contract", "version": "0.4.0-draft", "description": "ILLUSTRATIVE ONLY. Generated from the Phase 4 website specification. Not a production API or a commitment to availability. No biometric uploads are supported by the website simulator." }, "servers": [ { "url": "https://palmid.example.invalid/api/v1", "description": "Reserved non-production example host; replace only after onboarding." } ], "security": [ { "bearerAuth": [], "mutualTLS": [] } ], "paths": { "/enrollments": { "post": { "operationId": "enrollments", "summary": "Palm enrollment", "description": "Bind a reference to an authoritative record after processing-basis checks. Target contract; implementation and status require approval.", "tags": [ "Target contract" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target semantics: key is scoped to client and tenant; replay only the same logical request with the same body." } ], "responses": { "201": { "description": "Illustrative result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentsResponse" }, "example": { "requestId": "demo-request-001", "traceId": "demo-trace-001", "service": "enrollments", "modelStatus": "ILLUSTRATIVE_ONLY", "enrollmentRef": "demo-enrollment-001", "enrollmentState": "PENDING_REVIEW", "evidenceRef": "demo-evidence-001" } } } }, "400": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentsRequest" }, "example": { "requestId": "demo-request-001", "tenantRef": "demo-hospital-a", "purpose": "patient-verification", "deviceRef": "demo-device-001", "subjectRef": "demo-patient-001", "identityProofRef": "demo-proof-001", "processingBasisRef": "demo-basis-001", "captureRef": "demo-capture-001" } } } } } }, "/identify": { "post": { "operationId": "identify", "summary": "Identify 1:N", "description": "Resolve identity within an authorized population. Target contract; implementation and status require approval.", "tags": [ "Target contract" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target semantics: key is scoped to client and tenant; replay only the same logical request with the same body." } ], "responses": { "200": { "description": "Illustrative result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyResponse" }, "example": { "requestId": "demo-request-001", "traceId": "demo-trace-001", "service": "identify", "modelStatus": "ILLUSTRATIVE_ONLY", "identityResult": "IDENTIFIED", "subjectRef": "demo-patient-001", "authorizationDecision": "NOT_EVALUATED", "evidenceRef": "demo-evidence-001" } } } }, "400": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyRequest" }, "example": { "requestId": "demo-request-001", "tenantRef": "demo-hospital-a", "purpose": "patient-verification", "deviceRef": "demo-device-001", "captureRef": "demo-capture-001", "populationRef": "demo-hospital-a-enrolled" } } } } } }, "/verify": { "post": { "operationId": "verify", "summary": "Verify 1:1", "description": "Compare a palm with the claimed identity. Target contract; implementation and status require approval.", "tags": [ "Target contract" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target semantics: key is scoped to client and tenant; replay only the same logical request with the same body." } ], "responses": { "200": { "description": "Illustrative result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" }, "example": { "requestId": "demo-request-001", "traceId": "demo-trace-001", "service": "verify", "modelStatus": "ILLUSTRATIVE_ONLY", "identityResult": "VERIFIED", "subjectRef": "demo-patient-001", "authorizationDecision": "NOT_EVALUATED", "evidenceRef": "demo-evidence-001" } } } }, "400": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" }, "example": { "requestId": "demo-request-001", "tenantRef": "demo-hospital-a", "purpose": "patient-verification", "deviceRef": "demo-device-001", "captureRef": "demo-capture-001", "subjectRef": "demo-patient-001", "businessContextRef": "demo-order-001" } } } } } }, "/presence": { "post": { "operationId": "presence", "summary": "Presence", "description": "Record presence after session and device checks. Target contract; implementation and status require approval.", "tags": [ "Target contract" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target semantics: key is scoped to client and tenant; replay only the same logical request with the same body." } ], "responses": { "200": { "description": "Illustrative result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceResponse" }, "example": { "requestId": "demo-request-001", "traceId": "demo-trace-001", "service": "presence", "modelStatus": "ILLUSTRATIVE_ONLY", "presenceResult": "PRESENCE_RECORDED", "subjectRef": "demo-patient-001", "evidenceRef": "demo-evidence-001" } } } }, "400": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceRequest" }, "example": { "requestId": "demo-request-001", "tenantRef": "demo-hospital-a", "purpose": "patient-verification", "deviceRef": "demo-device-001", "verificationRef": "demo-verification-001", "sessionRef": "demo-session-001", "locationRef": "demo-lab-a" } } } } } }, "/authorizations": { "post": { "operationId": "authorizations", "summary": "Authorization", "description": "Evaluate action permission separately from biometric matching. Target contract; implementation and status require approval.", "tags": [ "Target contract" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Target semantics: key is scoped to client and tenant; replay only the same logical request with the same body." } ], "responses": { "200": { "description": "Illustrative result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationsResponse" }, "example": { "requestId": "demo-request-001", "traceId": "demo-trace-001", "service": "authorizations", "modelStatus": "ILLUSTRATIVE_ONLY", "authorizationDecision": "STEP_UP_REQUIRED", "policyRef": "demo-policy-001", "reasonCode": "ADDITIONAL_FACTOR_REQUIRED", "evidenceRef": "demo-evidence-001" } } } }, "400": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationsRequest" }, "example": { "requestId": "demo-request-001", "tenantRef": "demo-hospital-a", "purpose": "patient-verification", "deviceRef": "demo-device-001", "verificationRef": "demo-verification-001", "subjectRef": "demo-operator-001", "resourceRef": "demo-machine-001", "action": "operate", "policyRef": "demo-policy-001" } } } } } }, "/evidence/{id}": { "get": { "operationId": "evidence", "summary": "Retrieve evidence", "description": "Retrieve an authorized event, not a biometric template. Target contract; implementation and status require approval.", "tags": [ "Target contract" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "demo-evidence-001" } ], "responses": { "200": { "description": "Illustrative result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceResponse" }, "example": { "requestId": "demo-request-001", "traceId": "demo-trace-001", "service": "evidence", "modelStatus": "ILLUSTRATIVE_ONLY", "evidenceId": "demo-evidence-001", "subjectRef": "demo-patient-001", "purpose": "patient-verification", "deviceRef": "demo-device-001", "policyRef": "demo-policy-001", "eventTime": "2026-09-09T00:00:00Z", "timeSource": "SERVER_CLOCK_ILLUSTRATIVE", "integrityStatus": "NOT_EVALUATED", "evidenceRef": "demo-evidence-001" } } } }, "400": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Target error response; no identity decision implied.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "mutualTLS": { "type": "mutualTLS" } }, "schemas": { "EnrollmentsRequest": { "type": "object", "required": [ "requestId", "tenantRef", "purpose", "deviceRef", "subjectRef", "identityProofRef", "processingBasisRef", "captureRef" ], "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 256 }, "tenantRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 256 }, "deviceRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "subjectRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "identityProofRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "processingBasisRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "EnrollmentsResponse": { "type": "object", "required": [ "requestId", "traceId", "service", "modelStatus", "enrollmentRef", "enrollmentState", "evidenceRef" ], "properties": { "requestId": { "type": "string" }, "traceId": { "type": "string" }, "service": { "type": "string" }, "modelStatus": { "type": "string" }, "enrollmentRef": { "type": "string" }, "enrollmentState": { "type": "string" }, "evidenceRef": { "type": "string" } }, "additionalProperties": false }, "IdentifyRequest": { "type": "object", "required": [ "requestId", "tenantRef", "purpose", "deviceRef", "captureRef", "populationRef" ], "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 256 }, "tenantRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 256 }, "deviceRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "populationRef": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "IdentifyResponse": { "type": "object", "required": [ "requestId", "traceId", "service", "modelStatus", "identityResult", "subjectRef", "authorizationDecision", "evidenceRef" ], "properties": { "requestId": { "type": "string" }, "traceId": { "type": "string" }, "service": { "type": "string" }, "modelStatus": { "type": "string" }, "identityResult": { "type": "string" }, "subjectRef": { "type": "string" }, "authorizationDecision": { "type": "string" }, "evidenceRef": { "type": "string" } }, "additionalProperties": false }, "VerifyRequest": { "type": "object", "required": [ "requestId", "tenantRef", "purpose", "deviceRef", "captureRef", "subjectRef", "businessContextRef" ], "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 256 }, "tenantRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 256 }, "deviceRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "subjectRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "businessContextRef": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "VerifyResponse": { "type": "object", "required": [ "requestId", "traceId", "service", "modelStatus", "identityResult", "subjectRef", "authorizationDecision", "evidenceRef" ], "properties": { "requestId": { "type": "string" }, "traceId": { "type": "string" }, "service": { "type": "string" }, "modelStatus": { "type": "string" }, "identityResult": { "type": "string" }, "subjectRef": { "type": "string" }, "authorizationDecision": { "type": "string" }, "evidenceRef": { "type": "string" } }, "additionalProperties": false }, "PresenceRequest": { "type": "object", "required": [ "requestId", "tenantRef", "purpose", "deviceRef", "verificationRef", "sessionRef", "locationRef" ], "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 256 }, "tenantRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 256 }, "deviceRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "verificationRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "sessionRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "locationRef": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "PresenceResponse": { "type": "object", "required": [ "requestId", "traceId", "service", "modelStatus", "presenceResult", "subjectRef", "evidenceRef" ], "properties": { "requestId": { "type": "string" }, "traceId": { "type": "string" }, "service": { "type": "string" }, "modelStatus": { "type": "string" }, "presenceResult": { "type": "string" }, "subjectRef": { "type": "string" }, "evidenceRef": { "type": "string" } }, "additionalProperties": false }, "AuthorizationsRequest": { "type": "object", "required": [ "requestId", "tenantRef", "purpose", "deviceRef", "verificationRef", "subjectRef", "resourceRef", "action", "policyRef" ], "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 256 }, "tenantRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 256 }, "deviceRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "verificationRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "subjectRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "resourceRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "action": { "type": "string", "minLength": 1, "maxLength": 256 }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "AuthorizationsResponse": { "type": "object", "required": [ "requestId", "traceId", "service", "modelStatus", "authorizationDecision", "policyRef", "reasonCode", "evidenceRef" ], "properties": { "requestId": { "type": "string" }, "traceId": { "type": "string" }, "service": { "type": "string" }, "modelStatus": { "type": "string" }, "authorizationDecision": { "type": "string" }, "policyRef": { "type": "string" }, "reasonCode": { "type": "string" }, "evidenceRef": { "type": "string" } }, "additionalProperties": false }, "EvidenceRequest": { "type": "object", "required": [ "requestId", "tenantRef", "purpose", "deviceRef", "evidenceId" ], "additionalProperties": false, "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 256 }, "tenantRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 256 }, "deviceRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "evidenceId": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "EvidenceResponse": { "type": "object", "required": [ "requestId", "traceId", "service", "modelStatus", "evidenceId", "subjectRef", "purpose", "deviceRef", "policyRef", "eventTime", "timeSource", "integrityStatus", "evidenceRef" ], "properties": { "requestId": { "type": "string" }, "traceId": { "type": "string" }, "service": { "type": "string" }, "modelStatus": { "type": "string" }, "evidenceId": { "type": "string" }, "subjectRef": { "type": "string" }, "purpose": { "type": "string" }, "deviceRef": { "type": "string" }, "policyRef": { "type": "string" }, "eventTime": { "type": "string" }, "timeSource": { "type": "string" }, "integrityStatus": { "type": "string" }, "evidenceRef": { "type": "string" } }, "additionalProperties": false }, "Problem": { "type": "object", "required": [ "type", "title", "status", "code", "requestId" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "requestId": { "type": "string" }, "detail": { "type": "string" } } } } } }