openapi: 3.1.0 # Canonical path: ./common/components.yaml info: title: Quub Exchange - Shared Components version: 2.0.0 description: Shared components, schemas, and security definitions for reuse across all Quub APIs license: name: Proprietary url: https://quub.exchange/license servers: - url: https://api.quub.exchange description: Placeholder (this file contains only reusable components) paths: {} # This file contains only reusable components components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT oauth2: type: oauth2 description: OAuth 2.0 authorization with scope-based access control flows: authorizationCode: authorizationUrl: https://auth.quub.exchange/oauth/authorize tokenUrl: https://auth.quub.exchange/oauth/token scopes: # Service-specific scopes (read/write/admin pattern) read:analytics: Read access to analytics reports write:analytics: Create and update analytics reports read:banking: Read access to banking operations write:banking: Execute banking transactions read:chain: Read access to blockchain operations write:chain: Execute blockchain transactions read:compliance: Read access to compliance data write:compliance: Manage compliance rules and records admin:compliance: Administrative access to compliance operations read:custody: Read access to custodian operations write:custody: Execute custody operations admin:custody: Administrative access to custody read:data: Read access to data services write:data: Create and update data records read:documents: Read access to documents write:documents: Upload and manage documents read:escrow: Read access to escrow accounts write:escrow: Manage escrow operations read:events: Read access to event streams write:events: Publish events read:exchange: Read access to exchange operations write:exchange: Execute exchange trades read:fees: Read access to fees and billing write:fees: Manage fees and billing read:gateway: Read access to gateway status write:gateway: Manage gateway configuration read:governance: Read access to governance proposals write:governance: Create and vote on proposals admin:governance: Administrative access to governance read:identity: Read access to identity data write:identity: Manage identity records read:marketplace: Read access to marketplace listings write:marketplace: Create and manage listings read:notifications: Read access to notifications write:notifications: Send notifications read:observability: Read access to metrics and logs write:observability: Manage observability configuration read:pricing: Read access to pricing data write:pricing: Manage reference data read:primary: Read access to primary market offerings write:primary: Create and manage offerings read:risk: Read access to risk limits write:risk: Manage risk limits admin:risk: Administrative access to risk controls read:sandbox: Read access to sandbox environments write:sandbox: Manage sandbox resources read:settlements: Read access to settlement data write:settlements: Execute settlements read:tenancy: Read access to tenant configuration write:tenancy: Manage tenant settings admin:tenancy: Administrative access to tenant operations read:transfer-agent: Read access to transfer agent operations write:transfer-agent: Execute transfer operations read:treasury: Read access to treasury operations write:treasury: Execute treasury transactions admin:treasury: Administrative access to treasury # Global administrative scope admin:*: Administrative access to all resources clientCredentials: tokenUrl: https://auth.quub.exchange/oauth/token scopes: # Service-specific scopes (read/write/admin pattern) read:analytics: Read access to analytics reports write:analytics: Create and update analytics reports read:banking: Read access to banking operations write:banking: Execute banking transactions read:chain: Read access to blockchain operations write:chain: Execute blockchain transactions read:compliance: Read access to compliance data write:compliance: Manage compliance rules and records admin:compliance: Administrative access to compliance operations read:custody: Read access to custodian operations write:custody: Execute custody operations admin:custody: Administrative access to custody read:data: Read access to data services write:data: Create and update data records read:documents: Read access to documents write:documents: Upload and manage documents read:escrow: Read access to escrow accounts write:escrow: Manage escrow operations read:events: Read access to event streams write:events: Publish events read:exchange: Read access to exchange operations write:exchange: Execute exchange trades read:fees: Read access to fees and billing write:fees: Manage fees and billing read:gateway: Read access to gateway status write:gateway: Manage gateway configuration read:governance: Read access to governance proposals write:governance: Create and vote on proposals admin:governance: Administrative access to governance read:identity: Read access to identity data write:identity: Manage identity records read:marketplace: Read access to marketplace listings write:marketplace: Create and manage listings read:notifications: Read access to notifications write:notifications: Send notifications read:observability: Read access to metrics and logs write:observability: Manage observability configuration read:pricing: Read access to pricing data write:pricing: Manage reference data read:primary: Read access to primary market offerings write:primary: Create and manage offerings read:risk: Read access to risk limits write:risk: Manage risk limits admin:risk: Administrative access to risk controls read:sandbox: Read access to sandbox environments write:sandbox: Manage sandbox resources read:settlements: Read access to settlement data write:settlements: Execute settlements read:tenancy: Read access to tenant configuration write:tenancy: Manage tenant settings admin:tenancy: Administrative access to tenant operations read:transfer-agent: Read access to transfer agent operations write:transfer-agent: Execute transfer operations read:treasury: Read access to treasury operations write:treasury: Execute treasury transactions admin:treasury: Administrative access to treasury # Global administrative scope admin:*: Administrative access to all resources apiKey: type: apiKey in: header name: X-API-KEY description: Org-bound API key; include X-Signature and X-Timestamp on writes. mtls: type: mutualTLS description: Client certificate authentication for T3 institutional trust level clientCertificate: type: mutualTLS description: "(DEPRECATED: Use 'mtls' instead) Client certificate authentication" headers: Request-Id: description: Request correlation ID (UUID or ULID) schema: type: string minLength: 10 parameters: # Naming Convention: # - Parameter keys (YAML keys): camelCase (e.g., orgId, tokenClassId) # - Path/query parameter names: camelCase (e.g., name: orgId, name: cursor) # - HTTP header names: Header-Case (e.g., name: Idempotency-Key, name: X-Signature) # ----------------------------- # PATH PARAMETERS (camelCase) # ----------------------------- orgId: name: orgId in: path required: true schema: { $ref: "./primitives.yaml#/components/schemas/OrgId" } projectId: name: projectId in: path required: true schema: { $ref: "./primitives.yaml#/components/schemas/ProjectId" } tokenClassId: name: tokenClassId in: path required: true schema: { $ref: "./primitives.yaml#/components/schemas/TokenClassId" } accountId: name: accountId in: path required: true schema: { $ref: "./primitives.yaml#/components/schemas/AccountId" } offeringId: name: offeringId in: path required: true schema: { $ref: "./primitives.yaml#/components/schemas/OfferingId" } subscriptionId: name: subscriptionId in: path required: true schema: { $ref: "./primitives.yaml#/components/schemas/SubscriptionId" } # ----------------------------- # QUERY PARAMETERS (camelCase) # ----------------------------- # Note: cursor and limit are defined in ./common/pagination.yaml # Reference them as: $ref: "./common/pagination.yaml#/components/parameters/cursor" sort: name: sort in: query schema: { type: string } description: Sort expression (e.g., "createdAt:desc"). locale: name: locale in: query schema: { $ref: "./primitives.yaml#/components/schemas/Locale" } description: Requested content locale (server may fallback). fromDate: name: fromDate in: query schema: { type: string, format: date } toDate: name: toDate in: query schema: { type: string, format: date } # Useful cross-spec filters (reference as needed) tokenClassIdQuery: name: tokenClassId in: query schema: { $ref: "./primitives.yaml#/components/schemas/TokenClassId" } projectIdQuery: name: projectId in: query schema: { $ref: "./primitives.yaml#/components/schemas/ProjectId" } accountIdQuery: name: accountId in: query schema: { $ref: "./primitives.yaml#/components/schemas/AccountId" } # ----------------------------- # HEADERS (canonical header-case in `name`) # ----------------------------- orgIdHeader: name: X-Org-Id in: header required: false schema: { $ref: "./primitives.yaml#/components/schemas/OrgId" } description: Optional tenant assertion header (must match path orgId where required) idempotencyKey: name: Idempotency-Key in: header schema: { type: string, maxLength: 128 } signature: name: X-Signature in: header schema: { type: string } description: Base64(HMAC-SHA256) of (method|path|query|timestamp|body-sha256). timestamp: name: X-Timestamp in: header schema: { type: string, format: date-time } description: RFC3339; reject if skew > 5 minutes. responses: LocaleHeaders: description: Localized response headers headers: Content-Language: { schema: { type: string } } X-Locale-Fallback: { schema: { type: boolean } } schemas: {} # Note: Domain models moved to ./domain-models.yaml # Primitives (IDs, enums) moved to ./primitives.yaml # Error schemas moved to ./errors.yaml # Pagination schemas moved to ./pagination.yaml