{ "openapi": "3.0.4", "info": { "title": "FlexiMetaDoc External Integrations API", "description": "Inbound external integration endpoints only. This document intentionally excludes internal and UI endpoints.", "version": "v1" }, "paths": { "/api/v1/integrations/tenants/{tenantId}/status": { "get": { "tags": [ "ExternalIntegrationInbound" ], "description": "Authentication: use `ExternalIntegrationApiKey` for external callers. `Bearer` is documented for platform migration compatibility only.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Api-Version", "in": "header", "schema": { "type": "string" } }, { "name": "X-Integration-Key", "in": "header", "description": "Required integration API key identifier.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Timestamp", "in": "header", "description": "Required Unix epoch timestamp (seconds). Must be within allowed clock skew.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Nonce", "in": "header", "description": "Required replay-protection nonce. Contract requires UUID format (`[0-9a-fA-F-]`) with fixed length 36 and uniqueness scoped to clientId + nonce.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Signature", "in": "header", "description": "Required uppercase hex HMAC-SHA256 signature over canonical request.", "required": true, "schema": { "type": "string" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Optional client correlation id for end-to-end traceability.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationStatusDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationStatusDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationStatusDto" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "webhook-verification-failure": { "summary": "Signature verification failure", "description": "Signature verification failure error example." } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } } } } }, "security": [ { } ] } }, "/api/v1/integrations/tenants/{tenantId}/identities": { "post": { "tags": [ "ExternalIntegrationInbound" ], "description": "Authentication: use `ExternalIntegrationApiKey` for external callers. `Bearer` is documented for platform migration compatibility only.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Api-Version", "in": "header", "schema": { "type": "string" } }, { "name": "X-Integration-Key", "in": "header", "description": "Required integration API key identifier.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Timestamp", "in": "header", "description": "Required Unix epoch timestamp (seconds). Must be within allowed clock skew.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Nonce", "in": "header", "description": "Required replay-protection nonce. Contract requires UUID format (`[0-9a-fA-F-]`) with fixed length 36 and uniqueness scoped to clientId + nonce.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Signature", "in": "header", "description": "Required uppercase hex HMAC-SHA256 signature over canonical request.", "required": true, "schema": { "type": "string" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Optional client correlation id for end-to-end traceability.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationIdentityCreateRequestDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationIdentityCreateRequestDto" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/IntegrationIdentityCreateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationIdentityCreateResponseDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationIdentityCreateResponseDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationIdentityCreateResponseDto" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorEnvelopeDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorEnvelopeDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorEnvelopeDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorEnvelopeDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } } } } }, "security": [ { } ] } }, "/api/v1/integrations/tenants/{tenantId}/ping": { "post": { "tags": [ "ExternalIntegrationInbound" ], "description": "Authentication: use `ExternalIntegrationApiKey` for external callers. `Bearer` is documented for platform migration compatibility only.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Api-Version", "in": "header", "schema": { "type": "string" } }, { "name": "X-Integration-Key", "in": "header", "description": "Required integration API key identifier.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Timestamp", "in": "header", "description": "Required Unix epoch timestamp (seconds). Must be within allowed clock skew.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Nonce", "in": "header", "description": "Required replay-protection nonce. Contract requires UUID format (`[0-9a-fA-F-]`) with fixed length 36 and uniqueness scoped to clientId + nonce.", "required": true, "schema": { "type": "string" } }, { "name": "X-Integration-Signature", "in": "header", "description": "Required uppercase hex HMAC-SHA256 signature over canonical request.", "required": true, "schema": { "type": "string" } }, { "name": "X-Correlation-Id", "in": "header", "description": "Optional client correlation id for end-to-end traceability.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Required for write idempotency. 1..128 characters.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationPingRequestDto" }, "examples": { "success": { "summary": "Successful ping payload", "description": "Example available in integration API docs." }, "failure-validation": { "summary": "Validation failure payload", "description": "Validation failure payload example." } } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationPingRequestDto" }, "examples": { "success": { "summary": "Successful ping payload", "description": "Example available in integration API docs." }, "failure-validation": { "summary": "Validation failure payload", "description": "Validation failure payload example." } } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/IntegrationPingRequestDto" }, "examples": { "success": { "summary": "Successful ping payload", "description": "Example available in integration API docs." }, "failure-validation": { "summary": "Validation failure payload", "description": "Validation failure payload example." } } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationPingResponseDto" }, "examples": { "first-success": { "summary": "First execution", "description": "First execution example payload." }, "idempotent-replay": { "summary": "Idempotent retry replay", "description": "Idempotent replay example payload." } } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationPingResponseDto" }, "examples": { "first-success": { "summary": "First execution", "description": "First execution example payload." }, "idempotent-replay": { "summary": "Idempotent retry replay", "description": "Idempotent replay example payload." } } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationPingResponseDto" }, "examples": { "first-success": { "summary": "First execution", "description": "First execution example payload." }, "idempotent-replay": { "summary": "Idempotent retry replay", "description": "Idempotent replay example payload." } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" }, "examples": { "validation-failure": { "summary": "Payload validation failure", "description": "Validation failure error example." } } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" }, "examples": { "validation-failure": { "summary": "Payload validation failure", "description": "Validation failure error example." } } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" }, "examples": { "validation-failure": { "summary": "Payload validation failure", "description": "Validation failure error example." } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "webhook-verification-failure": { "summary": "Signature verification failure", "description": "Signature verification failure error example." } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } } } }, "409": { "description": "Conflict", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" }, "examples": { "idempotency-in-progress": { "summary": "Concurrent duplicate request", "description": "Idempotency conflict error example." } } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" }, "examples": { "idempotency-in-progress": { "summary": "Concurrent duplicate request", "description": "Idempotency conflict error example." } } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" }, "examples": { "idempotency-in-progress": { "summary": "Concurrent duplicate request", "description": "Idempotency conflict error example." } } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IntegrationErrorDto" } } } } }, "security": [ { } ] } } }, "components": { "schemas": { "IntegrationDeprecationPolicyDto": { "type": "object", "properties": { "Version": { "type": "string", "nullable": true }, "Policy": { "type": "string", "nullable": true }, "SunsetDateUtc": { "type": "string", "format": "date", "nullable": true }, "ReplacementVersion": { "type": "string", "nullable": true } }, "additionalProperties": false }, "IntegrationErrorDetailDto": { "type": "object", "properties": { "Field": { "type": "string", "nullable": true }, "Code": { "type": "string", "nullable": true }, "Message": { "type": "string", "nullable": true } }, "additionalProperties": false }, "IntegrationErrorDto": { "type": "object", "properties": { "Code": { "type": "string", "nullable": true }, "Message": { "type": "string", "nullable": true }, "CorrelationId": { "type": "string", "nullable": true }, "TenantId": { "type": "string", "format": "uuid", "nullable": true }, "IdempotencyKey": { "type": "string", "nullable": true }, "ValidationErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "nullable": true } }, "additionalProperties": false }, "IntegrationErrorEnvelopeDto": { "type": "object", "properties": { "ErrorCode": { "type": "string", "nullable": true }, "CorrelationId": { "type": "string", "nullable": true }, "Errors": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationErrorDetailDto" }, "nullable": true } }, "additionalProperties": false }, "IntegrationIdentityCreateRequestDto": { "required": [ "DisplayName", "ServiceEmail" ], "type": "object", "properties": { "ServiceEmail": { "maxLength": 320, "minLength": 0, "type": "string" }, "DisplayName": { "maxLength": 200, "minLength": 0, "type": "string" } }, "additionalProperties": false }, "IntegrationIdentityCreateResponseDto": { "type": "object", "properties": { "IdentityId": { "type": "string", "format": "uuid" }, "TenantId": { "type": "string", "format": "uuid" }, "ServiceEmail": { "type": "string", "nullable": true }, "DisplayName": { "type": "string", "nullable": true }, "CorrelationId": { "type": "string", "nullable": true } }, "additionalProperties": false }, "IntegrationPingRequestDto": { "type": "object", "properties": { "Message": { "maxLength": 256, "minLength": 0, "type": "string", "nullable": true } }, "additionalProperties": false }, "IntegrationPingResponseDto": { "type": "object", "properties": { "Accepted": { "type": "boolean" }, "TenantId": { "type": "string", "format": "uuid" }, "Echo": { "type": "string", "nullable": true }, "CorrelationId": { "type": "string", "nullable": true }, "IdempotencyKey": { "type": "string", "nullable": true }, "ReplayedFromIdempotencyCache": { "type": "boolean" }, "DeprecationPolicy": { "$ref": "#/components/schemas/IntegrationDeprecationPolicyDto" } }, "additionalProperties": false }, "IntegrationStatusDto": { "type": "object", "properties": { "ClientId": { "type": "string", "nullable": true }, "TenantId": { "type": "string", "format": "uuid" }, "GrantedScopes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "CorrelationId": { "type": "string", "nullable": true }, "DeprecationPolicy": { "$ref": "#/components/schemas/IntegrationDeprecationPolicyDto" } }, "additionalProperties": false }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": { } } }, "securitySchemes": { "ExternalIntegrationApiKey": { "type": "apiKey", "description": "Required API key identifier header for external integration clients.", "name": "X-Integration-Key", "in": "header" }, "Bearer": { "type": "http", "description": "Optional bearer token scheme for migration/bridge scenarios. External integrations should prefer signed API key headers.", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "ExternalIntegrationInbound" } ] }