{ "openapi": "3.1.0", "info": { "title": "ChargeBridge Identity Service API", "version": "1.1.0", "description": "Identity resolution, risk scoring, enforcement policy, SLA monitoring, partner lifecycle management, and portal authentication for the ChargeBridge EV Roaming Hub. Request bodies are generated from the runtime Zod schemas (zod-to-json-schema) where the handler actually parses one; operations carry `x-consumer` (hub-ops | partner | internal | public) for scope-filtered client generation. This service has no Zod-backed response schemas yet — all success responses carry `x-unvalidated: true` with field names taken verbatim from the wire type / mapper function that actually builds them.", "contact": { "name": "ChargeBridge Engineering" } }, "servers": [ { "url": "http://localhost:3002", "description": "Local development" }, { "url": "https://api.dev.egridium.com", "description": "Development environment" } ], "tags": [ { "name": "Identity", "description": "Identity resolution and management across protocols" }, { "name": "Signals", "description": "Risk signal reporting and resolution" }, { "name": "Enforcement", "description": "Graduated enforcement policies and authorization" }, { "name": "SLA", "description": "SLA monitoring, dashboard, and per-partner configuration" }, { "name": "Partners", "description": "Partner lifecycle management (invite, activate, suspend, terminate)" }, { "name": "Auth", "description": "Portal user authentication (login, refresh, logout, session) and user management" }, { "name": "Internal", "description": "Internal service endpoints (trust lookup, portal linking)" }, { "name": "Health", "description": "Service health and metrics" } ], "paths": { "/health": { "get": { "tags": ["Health"], "summary": "Health check with database connectivity", "operationId": "getHealth", "x-consumer": "public", "security": [], "responses": { "200": { "description": "Service is healthy", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "ok", "service": "identity-service", "checks": { "database": "ok" } } } } } } } }, "/metrics": { "get": { "tags": ["Health"], "summary": "Prometheus metrics", "operationId": "getMetrics", "x-consumer": "public", "security": [], "responses": { "200": { "description": "Prometheus text format metrics", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/v1/identity/resolve": { "post": { "tags": ["Identity"], "summary": "Resolve or create a unified identity", "operationId": "resolveIdentity", "x-consumer": "internal", "description": "Resolves a protocol-specific identifier to a unified identity. Optionally creates a new identity if not found (create_if_not_found).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol": { "type": "string", "enum": [ "ISO_15118_PNC", "OCPI_2_2_1", "AUTOCHARGE", "RFID", "MOBILE_APP", "AD_HOC" ] }, "protocol_identifier": { "type": "object", "properties": { "token_uid": { "type": "string" }, "token_type": { "type": "string" }, "issuer_country_code": { "type": "string", "maxLength": 2 }, "issuer_party_id": { "type": "string", "maxLength": 3 }, "contract_id": { "type": "string" }, "vin": { "type": "string" }, "pcid": { "type": "string" }, "cert_fingerprint": { "type": "string" }, "issuer": { "type": "string" }, "ev_mac_hash": { "type": "string" }, "charger_vendor": { "type": "string" }, "first_seen_evse_id": { "type": "string" }, "rfid_uid": { "type": "string" }, "card_type": { "type": "string" }, "visual_number": { "type": "string" }, "user_id": { "type": "string" }, "app_id": { "type": "string" }, "device_fingerprint": { "type": "string" }, "two_factor_verified": { "type": "boolean" } }, "additionalProperties": false }, "verification_data": { "type": "object", "properties": { "certificate_valid": { "type": "boolean" }, "certificate_expires_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$" }, "two_factor_verified": { "type": "boolean" }, "biometric_verified": { "type": "boolean" }, "whitelist_status": { "type": "string" }, "issuer_trust_level": { "type": "string" } }, "additionalProperties": false }, "context": { "type": "object", "properties": { "evse_id": { "type": "string" }, "location_id": { "type": "string" }, "cpo_party_key": { "type": "string", "minLength": 1 }, "is_offline": { "type": "boolean" }, "timestamp": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$" } }, "required": ["cpo_party_key"], "additionalProperties": false }, "create_if_not_found": { "type": "boolean" } }, "required": ["protocol", "protocol_identifier", "context"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Identity resolved (existing)", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "identity_type": "VERIFIED", "primary_protocol": "OCPI_2_2_1", "primary_identifier": "DE-CBH-TOKEN-001", "strength": "STRONG", "trust_score": 82, "trust_tier": "GOLD", "fraud_flags": [], "created_at": "2026-01-15T10:30:00.000Z", "last_seen_at": "2026-01-15T10:30:00.000Z" }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } }, "201": { "description": "Identity created", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "identity_type": "PROVISIONAL", "primary_protocol": "OCPI_2_2_1", "primary_identifier": "DE-CBH-TOKEN-001", "strength": "WEAK", "trust_score": 50, "trust_tier": "SILVER", "fraud_flags": [], "created_at": "2026-01-15T10:30:00.000Z", "last_seen_at": "2026-01-15T10:30:00.000Z" }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": ["error", "message"] }, "example": { "error": "Bad Request", "message": "Validation failed: field: message" } } } } } } }, "/api/v1/identity/{id}": { "get": { "tags": ["Identity"], "summary": "Get identity by ID", "operationId": "getIdentity", "x-consumer": "internal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identity UUID" } ], "responses": { "200": { "description": "Identity details", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "identity_type": "VERIFIED", "primary_protocol": "OCPI_2_2_1", "primary_identifier": "DE-CBH-TOKEN-001", "strength": "STRONG", "trust_score": 82, "trust_tier": "GOLD", "fraud_flags": [], "created_at": "2026-01-15T10:30:00.000Z", "last_seen_at": "2026-01-15T10:30:00.000Z" }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } }, "404": { "description": "Identity not found", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": null, "status_code": 2003, "status_message": "Identity not found", "timestamp": "2026-01-15T10:30:00.000Z" } } } } } } }, "/api/v1/identity/{id}/signals": { "post": { "tags": ["Signals"], "summary": "Report a risk signal on an identity", "operationId": "reportSignal", "x-consumer": "internal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identity UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signal_type": { "type": "string", "enum": [ "NON_PAYMENT", "FRAUD_SUSPECTED", "VELOCITY_EXCEEDED", "IDENTITY_THEFT", "CHARGEBACK_PATTERN", "SUSPICIOUS_BEHAVIOR", "ACCOUNT_TAKEOVER", "GEOGRAPHIC_ANOMALY", "DEVICE_MISMATCH" ] }, "severity": { "type": "string", "enum": ["INFO", "WARNING", "CRITICAL"], "default": "WARNING" }, "scope": { "type": "string", "enum": ["SPECIFIC_IDENTITY", "ISSUER", "NETWORK_WIDE"], "default": "SPECIFIC_IDENTITY" }, "evidence_data": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1 }, "transaction_ref": { "type": "string" }, "amount_involved": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "occurred_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$" }, "supporting_data": { "type": "object", "additionalProperties": {} } }, "required": ["description"], "additionalProperties": false } }, "required": ["signal_type", "evidence_data"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Signal reported (aggregated into existing)", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b3e5c1a0-aaaa-4bbb-9ccc-000000000001", "target_identity_id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "signal_type": "FRAUD_SUSPECTED", "scope": "SPECIFIC_IDENTITY", "severity": "WARNING", "evidence_level": "MULTIPLE_REPORTS", "reporter_count": 2, "status": "ACTIVE", "reported_at": "2026-01-15T10:30:00.000Z", "evidence": [ { "description": "Repeated failed auth attempts" } ] }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } }, "201": { "description": "Signal reported (new)", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b3e5c1a0-aaaa-4bbb-9ccc-000000000001", "target_identity_id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "signal_type": "FRAUD_SUSPECTED", "scope": "SPECIFIC_IDENTITY", "severity": "WARNING", "evidence_level": "SINGLE_REPORT", "reporter_count": 1, "status": "ACTIVE", "reported_at": "2026-01-15T10:30:00.000Z", "evidence": [ { "description": "Repeated failed auth attempts" } ] }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": ["error", "message"] }, "example": { "error": "Bad Request", "message": "Validation failed: field: message" } } } } } }, "get": { "tags": ["Signals"], "summary": "Get risk signals for an identity", "operationId": "getSignals", "x-consumer": "internal", "description": "Query (offset/limit) NOT Zod-parsed — read via `request.query as any` (server.ts:222), only offset/limit are honoured (parsePaginationParams).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identity UUID" } ], "responses": { "200": { "description": "List of risk signals (also sets X-Total-Count/X-Limit/X-Offset headers)", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "b3e5c1a0-aaaa-4bbb-9ccc-000000000001", "target_identity_id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "signal_type": "FRAUD_SUSPECTED", "scope": "SPECIFIC_IDENTITY", "severity": "WARNING", "evidence_level": "SINGLE_REPORT", "reporter_count": 1, "status": "ACTIVE", "reported_at": "2026-01-15T10:30:00.000Z", "evidence": [] } ], "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z", "total_count": 1, "offset": 0, "limit": 50 } } } } } } }, "/api/v1/signals/{id}/resolve": { "post": { "tags": ["Signals"], "summary": "Resolve a risk signal", "operationId": "resolveSignal", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signal UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1 } }, "required": ["reason"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Signal resolved", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b3e5c1a0-aaaa-4bbb-9ccc-000000000001", "target_identity_id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "signal_type": "FRAUD_SUSPECTED", "scope": "SPECIFIC_IDENTITY", "severity": "WARNING", "evidence_level": "SINGLE_REPORT", "reporter_count": 1, "status": "RESOLVED", "reported_at": "2026-01-15T10:30:00.000Z", "resolved_at": "2026-01-15T11:00:00.000Z", "confirmation_reason": "Verified legitimate usage", "evidence": [] }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": ["error", "message"] }, "example": { "error": "Bad Request", "message": "Validation failed: field: message" } } } }, "404": { "description": "Signal not found", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": null, "status_code": 2003, "status_message": "Signal not found", "timestamp": "2026-01-15T10:30:00.000Z" } } } } } } }, "/api/v1/identity/{id}/enforcement": { "get": { "tags": ["Enforcement"], "summary": "Get enforcement policies for an identity", "operationId": "getEnforcement", "x-consumer": "internal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identity UUID" } ], "responses": { "200": { "description": "Enforcement policy details", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "identity_id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "is_blocked": false, "requires_pre_auth": false, "requires_real_time_auth": false, "requires_step_up_auth": false, "restricted_locations": null, "total_active_restrictions": 0, "restriction_summary": "No active restrictions" }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } } } } }, "/api/v1/identity/{id}/authorization": { "post": { "tags": ["Enforcement"], "summary": "Evaluate authorization for an identity", "operationId": "evaluateAuthorization", "x-consumer": "internal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identity UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol": { "type": "string", "enum": [ "ISO_15118_PNC", "OCPI_2_2_1", "AUTOCHARGE", "RFID", "MOBILE_APP", "AD_HOC" ] }, "protocol_identifier": { "type": "object", "properties": { "token_uid": { "type": "string" }, "token_type": { "type": "string" }, "issuer_country_code": { "type": "string", "maxLength": 2 }, "issuer_party_id": { "type": "string", "maxLength": 3 }, "contract_id": { "type": "string" }, "vin": { "type": "string" }, "pcid": { "type": "string" }, "cert_fingerprint": { "type": "string" }, "issuer": { "type": "string" }, "ev_mac_hash": { "type": "string" }, "charger_vendor": { "type": "string" }, "first_seen_evse_id": { "type": "string" }, "rfid_uid": { "type": "string" }, "card_type": { "type": "string" }, "visual_number": { "type": "string" }, "user_id": { "type": "string" }, "app_id": { "type": "string" }, "device_fingerprint": { "type": "string" }, "two_factor_verified": { "type": "boolean" } }, "additionalProperties": false }, "verification_data": { "type": "object", "properties": { "certificate_valid": { "type": "boolean" }, "certificate_expires_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$" }, "two_factor_verified": { "type": "boolean" }, "biometric_verified": { "type": "boolean" }, "whitelist_status": { "type": "string" }, "issuer_trust_level": { "type": "string" } }, "additionalProperties": false }, "authorization": { "type": "object", "properties": { "evse_id": { "type": "string", "minLength": 1 }, "location_id": { "type": "string", "minLength": 1 }, "cpo_party_key": { "type": "string", "minLength": 1 }, "requested_kwh": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "is_offline": { "type": "boolean" } }, "required": [ "evse_id", "location_id", "cpo_party_key", "is_offline" ], "additionalProperties": false } }, "required": [ "protocol", "protocol_identifier", "authorization" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Authorization decision", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "allowed": true, "identity_created": false, "confidence": 0.95, "notes": [], "trust_tier": "GOLD", "trust_score": 82, "restrictions": [], "evaluated_at": "2026-01-15T10:30:00.000Z" }, "status_code": 1000, "timestamp": "2026-01-15T10:30:00.000Z" } } } } } } }, "/api/v1/sla/dashboard": { "get": { "tags": ["SLA"], "summary": "Get SLA monitoring dashboard", "operationId": "getSlaDashboard", "x-consumer": "hub-ops", "responses": { "200": { "description": "SLA dashboard metrics", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "partners": [], "statistics": { "total_partners": 0, "healthy": 0, "warning": 0, "degraded": 0, "critical": 0, "total_open_violations": 0 } } } } } } } } }, "/api/v1/sla/partners": { "get": { "tags": ["SLA"], "summary": "Get SLA status per partner", "operationId": "getSlaPartners", "x-consumer": "hub-ops", "responses": { "200": { "description": "SLA status per partner", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "party_country_code": "DE", "party_id": "CBH", "overall_status": "HEALTHY", "open_violations": 0, "config": { "id": "3c1a2b4d-0000-4000-8000-000000000001", "party_country_code": "DE", "party_id": "CBH", "thresholds": [], "evaluation_interval_minutes": 15, "created_at": "2026-01-15T10:30:00.000Z", "updated_at": "2026-01-15T10:30:00.000Z", "version": 0 } } ] } } } } } } }, "/api/v1/sla/configs": { "post": { "tags": ["SLA"], "summary": "Create SLA configuration for a party", "operationId": "createSlaConfig", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "party_country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "party_id": { "type": "string", "minLength": 1, "maxLength": 3 }, "thresholds": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "RESPONSE_TIME_P95", "RESPONSE_TIME_P99", "UPTIME_PERCENTAGE", "ERROR_RATE", "DATA_FRESHNESS_HOURS" ] }, "warnThreshold": { "type": "number" }, "minorThreshold": { "type": "number" }, "majorThreshold": { "type": "number" }, "criticalThreshold": { "type": "number" }, "unit": { "type": "string", "minLength": 1 } }, "required": [ "metric", "warnThreshold", "minorThreshold", "majorThreshold", "criticalThreshold", "unit" ], "additionalProperties": false }, "minItems": 1 }, "evaluation_interval_minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "party_country_code", "party_id", "thresholds", "evaluation_interval_minutes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "SLA config created", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "3c1a2b4d-0000-4000-8000-000000000001", "party_country_code": "DE", "party_id": "CBH", "thresholds": [ { "metric": "RESPONSE_TIME_P95", "warn_threshold": 500, "minor_threshold": 1000, "major_threshold": 2000, "critical_threshold": 5000, "unit": "ms" } ], "evaluation_interval_minutes": 15, "created_at": "2026-01-15T10:30:00.000Z", "updated_at": "2026-01-15T10:30:00.000Z", "version": 0 } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": ["error", "message"] }, "example": { "error": "Bad Request", "message": "Validation failed: field: message" } } } }, "409": { "description": "SLA configuration already exists for this party", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "error": "Conflict", "message": "SLA configuration already exists for DE-CBH. Use PUT to update.", "existing_config_id": "3c1a2b4d-0000-4000-8000-000000000001" } } } } } } }, "/partners": { "get": { "tags": ["Partners"], "summary": "List all partners", "operationId": "listPartners", "x-consumer": "hub-ops", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": ["CPO", "EMSP", "HUB", "NSP"] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "INVITED", "ACCEPTED", "ACTIVE", "PAUSED", "SUSPENDED", "TERMINATED" ] } }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "party_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 3 } } ], "responses": { "200": { "description": "List of partners", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "9a1b2c3d-0000-4000-8000-000000000002", "country_code": "TR", "party_id": "PHT", "name": "Photinus Energy", "role": "CPO", "status": "ACTIVE", "website": null, "logo_url": null, "business_details": null, "created_at": "2026-01-15T10:30:00.000Z", "updated_at": "2026-01-15T10:30:00.000Z" } ], "total": 1, "limit": 20, "offset": 0 } } } } } }, "post": { "tags": ["Partners"], "summary": "Create a new partner", "operationId": "createPartner", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country_code": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "party_id": { "type": "string", "minLength": 1, "maxLength": 3, "pattern": "^\\S+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "type": "string", "enum": ["CPO", "EMSP", "HUB", "NSP"] }, "website": { "type": "string", "format": "uri", "maxLength": 500 }, "logo_url": { "type": "string", "format": "uri", "maxLength": 500 }, "business_details": { "type": "object", "additionalProperties": {} }, "tax_id": { "type": "string", "minLength": 1, "maxLength": 20 }, "legal_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "epdk_license_no": { "type": "string", "minLength": 1, "maxLength": 50 }, "membershipKind": { "type": "string", "enum": ["MEMBER", "GUEST_VIA_MEMBER"], "description": "Party kind (ADR-0084 K1). MEMBER = hub member; GUEST_VIA_MEMBER = guest party connected through a member via bilateral mesh (no hub relationship or hub fee for its pairs). Required, no default. Party-level: if the party already has a recorded kind (second role), the declared kind must match it, otherwise 409." }, "create_portal_user": { "type": "boolean", "default": false }, "admin_email": { "type": "string", "format": "email" }, "admin_name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "country_code", "party_id", "name", "role", "membershipKind" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Partner created", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "country_code": "TR", "party_id": "PHT", "name": "Photinus Energy", "role": "CPO", "status": "INVITED", "website": null, "logo_url": null, "business_details": null, "created_at": "2026-01-15T10:30:00.000Z", "updated_at": "2026-01-15T10:30:00.000Z" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "409": { "description": "Partner already exists, or declared membershipKind conflicts with the party's recorded kind (body carries existingMembershipKind)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner already exists, or declared membershipKind conflicts with the party's recorded kind (body carries existingMembershipKind)" } } } } } } }, "/partners/{id}": { "get": { "tags": ["Partners"], "summary": "Get partner by ID", "operationId": "getPartner", "x-consumer": "hub-ops", "description": "`id` accepts either a partner UUID or an org_id (party_id) string.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID or org_id" } ], "responses": { "200": { "description": "Partner details", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "country_code": "TR", "party_id": "PHT", "name": "Photinus Energy", "role": "CPO", "status": "ACTIVE", "website": null, "logo_url": null, "business_details": null, "created_at": "2026-01-15T10:30:00.000Z", "updated_at": "2026-01-15T10:30:00.000Z" } } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } } } }, "patch": { "tags": ["Partners"], "summary": "Update partner details", "operationId": "updatePartner", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "INVITED", "ACCEPTED", "ACTIVE", "PAUSED", "SUSPENDED", "TERMINATED" ] }, "website": { "type": "string", "format": "uri", "maxLength": 500, "nullable": true }, "logo_url": { "type": "string", "format": "uri", "maxLength": 500, "nullable": true }, "business_details": { "type": "object", "additionalProperties": {}, "nullable": true }, "tax_id": { "type": "string", "minLength": 1, "maxLength": 20, "nullable": true }, "legal_name": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true }, "epdk_license_no": { "type": "string", "minLength": 1, "maxLength": 50, "nullable": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Partner updated", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "country_code": "TR", "party_id": "PHT", "name": "Photinus Energy", "role": "CPO", "status": "ACTIVE", "website": null, "logo_url": null, "business_details": null, "created_at": "2026-01-15T10:30:00.000Z", "updated_at": "2026-01-15T10:30:00.000Z" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } } } } }, "/partners/{id}/invite": { "post": { "tags": ["Partners"], "summary": "Send partner invitation", "operationId": "invitePartner", "x-consumer": "hub-ops", "description": "Valid only from INVITED or TERMINATED status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Invitation sent", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "status": "INVITED" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } }, "409": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid status transition" } } } } } } }, "/partners/{id}/activate": { "post": { "tags": ["Partners"], "summary": "Activate a partner", "operationId": "activatePartner", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Partner activated", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "status": "ACTIVE" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } }, "409": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid status transition" } } } } } } }, "/partners/{id}/suspend": { "post": { "tags": ["Partners"], "summary": "Suspend a partner", "operationId": "suspendPartner", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Partner suspended", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "status": "SUSPENDED" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } }, "409": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid status transition" } } } } } } }, "/partners/{id}/pause": { "post": { "tags": ["Partners"], "summary": "Pause a partner", "operationId": "pausePartner", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Partner paused", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "status": "PAUSED" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } }, "409": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid status transition" } } } } } } }, "/partners/{id}/terminate": { "post": { "tags": ["Partners"], "summary": "Terminate a partner", "operationId": "terminatePartner", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Partner terminated", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000002", "status": "TERMINATED" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } }, "409": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid status transition" } } } } } } }, "/partners/{id}/contract-documents": { "post": { "tags": ["Contract Documents"], "summary": "Upload a signed membership contract (PDF, multipart)", "operationId": "uploadContractDocument", "x-consumer": "partner", "description": "multipart/form-data: metadata alanları DOSYA part'ından ÖNCE, sonra `file` (Content-Type application/pdf, %PDF- magic bytes; aksi 415). Sınır 20971520 bayt (Content-Length ve multipart fileSize; 413). Süreç içi rate limit 10/dk (kullanıcı başına). `note` kabul edilir ama SAKLANMAZ (K2'de sütun yok). Belge deposu probe'u başarısızken 503 DOCUMENT_STORE_UNAVAILABLE.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "claimed_signed_at": { "type": "string" }, "claimed_effective_from": { "type": "string" }, "claimed_effective_to": { "type": "string" }, "note": { "type": "string", "maxLength": 500 }, "file": { "type": "string", "format": "binary" } }, "required": ["file"] } } } }, "responses": { "201": { "description": "Uploaded; status SCAN_PENDING", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "9a1b2c3d-0000-4000-8000-000000000010", "partnerId": "9a1b2c3d-0000-4000-8000-000000000002", "version": 1, "sha256": "0000000000000000000000000000000000000000000000000000000000000000", "sizeBytes": 123456, "mime": "application/pdf", "status": "SCAN_PENDING", "onBehalf": false } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } }, "409": { "description": "Partner status not eligible / duplicate sha256", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner status not eligible / duplicate sha256" } } } }, "413": { "description": "Contract document too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document too large" } } } }, "415": { "description": "Only PDF is accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Only PDF is accepted" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Rate limit exceeded" } } } }, "503": { "description": "Contract document store is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document store is unavailable" } } } } } }, "get": { "tags": ["Contract Documents"], "summary": "List contract documents of a partner (version ascending)", "operationId": "listContractDocuments", "x-consumer": "partner", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" } ], "responses": { "200": { "description": "Documents", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Partner not found" } } } } } } }, "/partners/{id}/contract-documents/{documentId}": { "get": { "tags": ["Contract Documents"], "summary": "Contract document metadata", "operationId": "getContractDocument", "x-consumer": "partner", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document UUID" } ], "responses": { "200": { "description": "Document", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": {} } } } }, "404": { "description": "Contract document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document not found" } } } } } } }, "/partners/{id}/contract-documents/{documentId}/content": { "get": { "tags": ["Contract Documents"], "summary": "Download contract PDF (service proxy stream, access ledger)", "operationId": "downloadContractDocument", "x-consumer": "partner", "description": "Presigned URL YOK (D7). Her indirme erişim defterine yazılır. SCAN_INFECTED → 410, taranmamış (UPLOADED/SCAN_PENDING) → 409. Rate limit 60/dk. Belge deposu probe'u başarısızken 503 DOCUMENT_STORE_UNAVAILABLE.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document UUID" } ], "responses": { "200": { "description": "PDF stream", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Contract document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document not found" } } } }, "409": { "description": "Not downloadable before scan", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Not downloadable before scan" } } } }, "410": { "description": "Quarantined", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Quarantined" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Rate limit exceeded" } } } }, "503": { "description": "Contract document store is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document store is unavailable" } } } } } } }, "/partners/{id}/contract-documents/{documentId}/verify": { "post": { "tags": ["Contract Documents"], "summary": "Verify (hub_operator, allowlisted, not the uploader)", "operationId": "verifyContractDocument", "x-consumer": "hub-ops", "description": "SCAN_CLEAN → VERIFIED; önceki VERIFIED sürümler SUPERSEDED; Object Lock GOVERNANCE +10 yıl; partner.contract.verified.v1 yayınlanır. Doğrulayan ≠ yükleyen (403 VERIFIER_IS_UPLOADER). CONTRACT_VERIFIER_SUBS boşsa 503 CONTRACT_VERIFIERS_NOT_CONFIGURED; belge deposu probe'u başarısızken 503 DOCUMENT_STORE_UNAVAILABLE.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verified_signed_at": { "type": "string", "nullable": true }, "verified_effective_from": { "type": "string" }, "verified_effective_to": { "type": "string", "nullable": true }, "note": { "type": "string", "maxLength": 500 } }, "required": ["verified_effective_from"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "status": "VERIFIED" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Contract document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document not found" } } } }, "409": { "description": "Invalid transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid transition" } } } }, "503": { "description": "Contract verifiers not configured / document store unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract verifiers not configured / document store unavailable" } } } } } } }, "/partners/{id}/contract-documents/{documentId}/reject": { "post": { "tags": ["Contract Documents"], "summary": "Reject (hub_operator, allowlisted); SCAN_CLEAN → REJECTED", "operationId": "rejectContractDocument", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": ["reason"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Rejected", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "status": "REJECTED" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Contract document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document not found" } } } }, "409": { "description": "Invalid transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid transition" } } } }, "503": { "description": "Contract verifiers not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract verifiers not configured" } } } } } } }, "/partners/{id}/contract-documents/{documentId}/revoke": { "post": { "tags": ["Contract Documents"], "summary": "Revoke (hub_operator, allowlisted); VERIFIED → REVOKED", "operationId": "revokeContractDocument", "x-consumer": "hub-ops", "description": "partner.contract.revoked.v1 yayınlanır.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Partner UUID" }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": ["reason"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Revoked", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "status": "REVOKED" } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Contract document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract document not found" } } } }, "409": { "description": "Invalid transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid transition" } } } }, "503": { "description": "Contract verifiers not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Contract verifiers not configured" } } } } } } }, "/contract-documents/pending": { "get": { "tags": ["Contract Documents"], "summary": "Hub verification queue (SCAN_CLEAN documents, all partners)", "operationId": "listPendingContractDocuments", "x-consumer": "hub-ops", "responses": { "200": { "description": "Pending documents with partner ref", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Forbidden" } } } } } } }, "/auth/login": { "post": { "tags": ["Auth"], "summary": "Portal user login", "operationId": "login", "x-consumer": "public", "security": [], "description": "On success, sets HttpOnly `cb_access` + `cb_refresh` cookies (Path=/auth for the refresh cookie) plus a non-HttpOnly CSRF double-submit cookie (auth.controller.ts:75-98). The JSON body below is also returned for non-browser/service callers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 }, "org_type": { "type": "string", "enum": ["hub_operator", "cpo", "emsp"] } }, "required": ["email", "password"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Login successful (sets cookies; parties[] claim embedded in JWT, ADR-0058)", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "access_token": "eyJhbGciOi...", "refresh_token": "a1b2c3d4...", "expires_in": 900, "token_type": "Bearer" } } } }, "401": { "description": "Invalid email or password", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Invalid email or password" } } } }, "403": { "description": "Account is not active", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Account is not active" } } } } } } }, "/auth/refresh": { "post": { "tags": ["Auth"], "summary": "Refresh access token", "operationId": "refreshToken", "x-consumer": "public", "security": [], "description": "No request body (NFR-2): the refresh token is read ONLY from the HttpOnly `cb_refresh` cookie (auth.controller.ts:339-347). A legacy client that sends the token in the body instead of the cookie gets 401 and must log in again. Rotates both cookies on success.", "responses": { "200": { "description": "Token refreshed (rotates cookies)", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "access_token": "eyJhbGciOi...", "refresh_token": "e5f6a7b8...", "expires_in": 900, "token_type": "Bearer" } } } }, "401": { "description": "Missing refresh token cookie", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Missing refresh token cookie" } } } } } } }, "/auth/logout": { "post": { "tags": ["Auth"], "summary": "Logout and revoke refresh token", "operationId": "logout", "x-consumer": "public", "security": [], "description": "Body is optional and NOT Zod-parsed — `body?.refresh_token` is read freely if present (auth.controller.ts:450-453); the cookie is used otherwise. Always clears cookies and returns 200.", "responses": { "200": { "description": "Logged out (clears cookies)", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Logged out" } } } } } } }, "/auth/me": { "get": { "tags": ["Auth"], "summary": "Current portal session (auth.controller.ts:423-441)", "operationId": "getAuthMe", "x-consumer": "partner", "description": "Replaces client-side JWT decode (NFR-1): shapes `request.user` (set by the global JWT hook) as-is. `parties` (ADR-0058) is ALWAYS an array, empty until the claim is populated.", "responses": { "200": { "description": "Session claims", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "sub": "1a2b3c4d-0000-4000-8000-000000000003", "email": "admin@example.com", "name": "Admin User", "org_id": "PHT", "org_type": "cpo", "roles": ["admin"], "parties": [ { "cc": "TR", "party_id": "PHT", "role": "CPO" } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "Authentication required" } } } } } } }, "/users": { "post": { "tags": ["Auth"], "summary": "Create a portal user", "operationId": "createUser", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "org_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "org_type": { "type": "string", "enum": ["hub_operator", "cpo", "emsp"] }, "roles": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "email", "name", "password", "org_id", "org_type", "roles" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "User created", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "1a2b3c4d-0000-4000-8000-000000000003", "email": "user@example.com", "name": "John Doe", "org_id": "PHT", "org_type": "cpo", "roles": ["admin"], "created_at": "2026-01-15T10:30:00.000Z", "last_login_at": null } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } }, "409": { "description": "User already exists for this org_type", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "User already exists for this org_type" } } } } } }, "get": { "tags": ["Auth"], "summary": "List portal users", "operationId": "listUsers", "x-consumer": "partner", "description": "Non-hub callers are narrowed to their own org_id/org_type (P0-5, auth.controller.ts:542-571) — never 403, empty page instead.", "parameters": [ { "name": "org_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "org_type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["hub_operator", "cpo", "emsp"] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["active", "inactive", "suspended"] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 100 } } ], "responses": { "200": { "description": "List of users", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "1a2b3c4d-0000-4000-8000-000000000003", "email": "user@example.com", "name": "John Doe", "org_id": "PHT", "org_type": "cpo", "roles": ["admin"], "created_at": "2026-01-15T10:30:00.000Z", "last_login_at": null } ], "total": 1, "page": 1, "limit": 50 } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message"] }, "example": { "message": "Validation failed", "errors": { "email": ["Invalid email"] } } } } } } } }, "/users/{id}": { "get": { "tags": ["Auth"], "summary": "Get portal user by ID", "operationId": "getUser", "x-consumer": "hub-ops", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User UUID" } ], "responses": { "200": { "description": "User details", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "1a2b3c4d-0000-4000-8000-000000000003", "email": "user@example.com", "name": "John Doe", "org_id": "PHT", "org_type": "cpo", "roles": ["admin"], "created_at": "2026-01-15T10:30:00.000Z", "last_login_at": null } } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "example": { "message": "User not found" } } } } } } }, "/internal/identities/{id}/trust": { "get": { "tags": ["Internal"], "summary": "Get identity trust info (internal only, for portal login)", "operationId": "getIdentityTrust", "x-consumer": "internal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identity UUID" } ], "responses": { "200": { "description": "Trust information", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "trustScore": 75, "trustTier": "GOLD", "primaryProtocol": "OCPI_2_2_1", "primaryIdentifier": "DE-CBH-TOKEN-001", "linkedProtocols": [], "enforcement": { "hasActiveEnforcement": false, "isBlocked": false, "totalRestrictions": 0, "restrictionSummary": "No active restrictions" } } } } } }, "403": { "description": "Invalid internal token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": ["success", "error"] }, "example": { "success": false, "error": "Invalid internal token" } } } }, "404": { "description": "Identity not found", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "error": "Identity not found: 6f9c2b1a-1234-4abc-8def-1234567890ab" } } } } } } }, "/internal/identities/link-portal": { "post": { "tags": ["Internal"], "summary": "Link portal user to identity (internal only)", "operationId": "linkPortalToIdentity", "x-consumer": "internal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "portalUserId": { "type": "string", "minLength": 1 }, "protocol": { "type": "string", "minLength": 1 }, "identifier": { "type": "string", "minLength": 1 } }, "required": ["portalUserId", "protocol", "identifier"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Identity linked", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "identityId": "6f9c2b1a-1234-4abc-8def-1234567890ab", "trustScore": 50, "trustTier": "SILVER", "linked": true } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": ["error", "message"] }, "example": { "error": "Bad Request", "message": "Validation failed: field: message" } } } }, "403": { "description": "Invalid internal token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": ["success", "error"] }, "example": { "success": false, "error": "Invalid internal token" } } } } } } }, "/internal/identities/by-protocol/{protocol}/{identifier}": { "get": { "tags": ["Internal"], "summary": "Lookup identity by protocol identifier (internal only)", "operationId": "getIdentityByProtocol", "x-consumer": "internal", "parameters": [ { "name": "protocol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identity protocol (e.g. OCPI_2_2_1, RFID)" }, { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Protocol-specific identifier" } ], "responses": { "200": { "description": "Identity details", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "id": "6f9c2b1a-1234-4abc-8def-1234567890ab", "trustScore": 75, "trustTier": "GOLD", "primaryProtocol": "OCPI_2_2_1", "primaryIdentifier": "DE-CBH-TOKEN-001" } } } } }, "403": { "description": "Invalid internal token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": ["success", "error"] }, "example": { "success": false, "error": "Invalid internal token" } } } }, "404": { "description": "Identity not found", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "error": "Identity not found for OCPI_2_2_1:DE-CBH-TOKEN-001" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token from portal login or internal service token" }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "cb_access", "description": "Portal access cookie (JWT)" }, "internalToken": { "type": "apiKey", "in": "header", "name": "X-Internal-Token", "description": "Internal service authentication token" } }, "schemas": {} }, "security": [ { "bearerAuth": [] } ] }