{"openapi":"3.0.0","info":{"title":"Platphorm Keys API","description":"Secure API Key Management Service","version":"1.0.0","contact":{"name":"Platphorm Support","url":"https://platphorm.dev"},"license":{"name":"MIT"}},"servers":[{"url":"https://platphorm-keys.vercel.app","description":"Production"},{"url":"http://localhost:3000","description":"Development"}],"tags":[{"name":"Health","description":"System health and status"},{"name":"Provisioning","description":"Self-service key provisioning (no auth required)"},{"name":"Keys","description":"API Key management operations"},{"name":"Telemetry","description":"Observability and monitoring"}],"paths":{"/api/v1/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Check the health status of the API","operationId":"getHealth","responses":{"200":{"description":"System is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string"},"checks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["pass","fail"]},"message":{"type":"string"},"latency_ms":{"type":"number"}}}}}}}}},"503":{"description":"System is unhealthy"}}}},"/api/v1/keys/provision":{"post":{"tags":["Provisioning"],"summary":"Self-Service Key Provisioning","description":"Create a new API key without authentication. Auto-generates client UUID, fingerprint, and trace ID.","operationId":"provisionKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable name for the key","example":"My Production Key"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write","delete","admin"]},"default":["read"],"description":"Permission scopes for the key"},"clientMetadata":{"type":"object","description":"Optional custom metadata"}}}}}},"responses":{"201":{"description":"API key provisioned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"},"key":{"type":"string","description":"Full API key (shown only once)"},"keyPrefix":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"clientUUID":{"type":"string","description":"Auto-generated client identifier"},"fingerprint":{"type":"string","description":"Browser/device fingerprint"},"traceId":{"type":"string","description":"OpenTelemetry trace ID"},"geo":{"type":"object","properties":{"country":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"}}}}}}},"headers":{"X-Client-UUID":{"schema":{"type":"string"},"description":"Client UUID"},"X-Fingerprint":{"schema":{"type":"string"},"description":"Device fingerprint"},"X-Trace-Id":{"schema":{"type":"string"},"description":"Trace ID"}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/telemetry":{"get":{"tags":["Telemetry"],"summary":"Get Telemetry Data","description":"Retrieve OpenTelemetry metrics, spans, and observability data","operationId":"getTelemetry","parameters":[{"name":"spans","in":"query","description":"Include recent spans","schema":{"type":"boolean","default":false}},{"name":"metrics","in":"query","description":"Include recent metrics","schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","description":"Maximum number of items to return","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"Telemetry data","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"activeSpans":{"type":"integer"},"completedSpans":{"type":"integer"},"totalMetrics":{"type":"integer"},"operations":{"type":"object"}}},"timestamp":{"type":"string","format":"date-time"},"spans":{"type":"array","items":{"type":"object"}},"metrics":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/v1/keys":{"get":{"tags":["Keys"],"summary":"List API Keys","description":"List all API keys for the authenticated tenant","operationId":"listKeys","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","description":"Filter by key status","required":false,"schema":{"type":"string","enum":["active","rotated","revoked"]}},{"name":"limit","in":"query","description":"Maximum number of results (default: 50)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Pagination cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"cursor":{"type":"string"},"hasMore":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Keys"],"summary":"Create API Key","description":"Create a new API key for the tenant","operationId":"createKey","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable name for the key"},"description":{"type":"string","description":"Optional description"},"expiresIn":{"type":"integer","description":"Expiration time in seconds (optional)"}}}}}},"responses":{"201":{"description":"API key created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/keys/{keyId}":{"get":{"tags":["Keys"],"summary":"Get API Key","description":"Retrieve details of a specific API key","operationId":"getKey","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Keys"],"summary":"Update API Key","description":"Update API key metadata","operationId":"updateKey","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"Key updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Keys"],"summary":"Revoke API Key","description":"Revoke an API key","operationId":"revokeKey","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Key revoked successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/keys/{keyId}/rotate":{"post":{"tags":["Keys"],"summary":"Rotate API Key","description":"Rotate an existing API key and generate a new secret","operationId":"rotateKey","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key rotated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/keys/validate":{"post":{"tags":["Keys"],"summary":"Validate API Key","description":"Validate an API key without revealing the full secret","operationId":"validateKey","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"API key to validate"}}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"keyId":{"type":"string"},"keyPrefix":{"type":"string"},"status":{"type":"string","enum":["active","rotated","revoked"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"schemas":{"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"keyPrefix":{"type":"string","description":"Public prefix of the key"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["active","rotated","revoked"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time"}}},"ApiKeyCreated":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Full API key (only shown once)"},"keyPrefix":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"object"},"requestId":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token for API authentication"}}}}