{
  "openapi": "3.1.0",
  "info": {
    "title": "UCap Public API",
    "version": "1.0.0",
    "description": "OAuth 2.0 authenticated API for versioned products, CRM opportunities, consent sessions, webhooks, and consumer self-service.",
    "contact": {
      "name": "UCap Developers",
      "url": "https://ucap.africa/developers"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://ucap.africa/api/public/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "OAuth",
      "description": "Authorization, token issuance, introspection, revocation."
    },
    {
      "name": "Me",
      "description": "Consumer self-service endpoints (require user token)."
    },
    {
      "name": "Sessions",
      "description": "Partner application/consent sessions."
    },
    {
      "name": "Products",
      "description": "Versioned partner product journeys."
    },
    {
      "name": "Opportunities",
      "description": "Consent-led CRM opportunities."
    },
    {
      "name": "Webhooks",
      "description": "Webhook endpoints and delivery diagnostics."
    },
    {
      "name": "System",
      "description": "Health and discovery."
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Access token issued by /oauth/token."
      },
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Partner client_id + client_secret. Accepted only at /oauth/token."
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://ucap.africa/oauth/authorize",
            "tokenUrl": "https://ucap.africa/api/public/v1/oauth/token",
            "refreshUrl": "https://ucap.africa/api/public/v1/oauth/token",
            "scopes": {
              "consumer.profile.read": "Read the consumer's profile, contacts, and addresses.",
              "consumer.profile.write": "Update the consumer's profile, contacts, and addresses.",
              "consumer.documents.read": "List and download the consumer's documents.",
              "consumer.documents.write": "Upload and delete the consumer's documents.",
              "consumer.grants.read": "List consent grants the consumer has issued.",
              "consumer.grants.revoke": "Revoke a consent grant the consumer has issued.",
              "consumer.history.read": "Read activity history for the consumer.",
              "consumer.notifications.read": "Read notifications addressed to the consumer.",
              "consumer.notifications.write": "Mark notifications as read for the consumer.",
              "consumer.consent.read": "Inspect pending consent sessions for the consumer.",
              "consumer.consent.respond": "Approve or deny a pending consent session."
            }
          },
          "clientCredentials": {
            "tokenUrl": "https://ucap.africa/api/public/v1/oauth/token",
            "scopes": {
              "partner.products.read": "Read the client's products and immutable versions.",
              "partner.products.write": "Create drafts and publish or archive products.",
              "partner.opportunities.read": "Search and read the client's opportunities.",
              "partner.opportunities.write": "Update opportunities, notes, tasks, and outcomes.",
              "partner.webhooks.read": "Read webhook endpoints and delivery diagnostics.",
              "partner.webhooks.write": "Manage webhook endpoints and redeliver events.",
              "sessions.create": "Create application sessions for a client.",
              "sessions.read": "Read application sessions and consented data.",
              "sessions.revoke": "Revoke an application session."
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "TokenResponse": {
        "type": "object",
        "required": [
          "access_token",
          "token_type",
          "expires_in"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "token_type": {
            "type": "string",
            "enum": [
              "Bearer"
            ]
          },
          "expires_in": {
            "type": "integer",
            "description": "Seconds until access_token expires."
          },
          "refresh_token": {
            "type": "string"
          },
          "scope": {
            "type": "string",
            "description": "Space-delimited granted scopes."
          },
          "id_token": {
            "type": "string",
            "description": "Issued only when openid scope is granted."
          }
        }
      },
      "Profile": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "first_name": {
            "type": "string",
            "nullable": true
          },
          "last_name": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "account_type": {
            "type": "string",
            "enum": [
              "consumer",
              "staff"
            ]
          },
          "status": {
            "type": "string"
          }
        }
      },
      "Contact": {
        "type": "object",
        "additionalProperties": true
      },
      "Address": {
        "type": "object",
        "additionalProperties": true
      },
      "Document": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "doc_type": {
            "type": "string"
          },
          "document_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "is_expired": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Consent": {
        "type": "object",
        "additionalProperties": true
      },
      "Grant": {
        "type": "object",
        "additionalProperties": true
      },
      "HistoryEvent": {
        "type": "object",
        "additionalProperties": true
      },
      "Notification": {
        "type": "object",
        "additionalProperties": true
      },
      "Session": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "opportunity_id": {
            "type": "string",
            "format": "uuid"
          },
          "session_url": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "granted",
              "denied",
              "expired",
              "revoked"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "name",
          "lifecycle_status",
          "environment"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "lifecycle_status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "archived"
            ]
          },
          "environment": {
            "type": "string",
            "enum": [
              "sandbox",
              "production"
            ]
          }
        }
      },
      "Opportunity": {
        "type": "object",
        "required": [
          "id",
          "product_id",
          "stage"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "product_id": {
            "type": "string",
            "format": "uuid"
          },
          "external_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "stage": {
            "type": "string",
            "enum": [
              "new",
              "consent_pending",
              "consent_granted",
              "in_review",
              "approved",
              "declined",
              "withdrawn",
              "closed"
            ]
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "required": [
          "id",
          "url",
          "subscribed_events",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "subscribed_events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy"
          }
        }
      }
    },
    "/oauth/metadata": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "summary": "Authorization-server discovery (RFC 8414)",
        "security": [],
        "responses": {
          "200": {
            "description": "Discovery document"
          }
        }
      }
    },
    "/oauth/authorize": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "summary": "Approve or deny an authorization request",
        "description": "Called by the consent UI at /oauth/authorize. Requires a first-party Supabase access token, NOT an API bearer token.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "decision",
                  "response_type",
                  "client_id",
                  "redirect_uri",
                  "scope",
                  "code_challenge",
                  "code_challenge_method"
                ],
                "properties": {
                  "decision": {
                    "type": "string",
                    "enum": [
                      "approve",
                      "deny"
                    ]
                  },
                  "response_type": {
                    "type": "string",
                    "enum": [
                      "code"
                    ]
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "redirect_uri": {
                    "type": "string",
                    "format": "uri"
                  },
                  "scope": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  },
                  "code_challenge": {
                    "type": "string",
                    "minLength": 43,
                    "maxLength": 128
                  },
                  "code_challenge_method": {
                    "type": "string",
                    "enum": [
                      "S256"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision recorded; client should navigate to redirect_to.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "redirect_to"
                  ],
                  "properties": {
                    "redirect_to": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "summary": "Exchange credentials/code for an access token",
        "security": [
          {
            "basicAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "authorization_code",
                      "client_credentials",
                      "refresh_token"
                    ]
                  },
                  "code": {
                    "type": "string"
                  },
                  "redirect_uri": {
                    "type": "string",
                    "format": "uri"
                  },
                  "code_verifier": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "scope": {
                    "type": "string"
                  },
                  "refresh_token": {
                    "type": "string"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Issued token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/oauth/revoke": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "summary": "Revoke a token (RFC 7009)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "token_type_hint": {
                    "type": "string",
                    "enum": [
                      "access_token",
                      "refresh_token"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked (or unknown token — RFC 7009 returns 200 either way)."
          }
        }
      }
    },
    "/oauth/introspect": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "summary": "Introspect a token (RFC 7662)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Introspection result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "active"
                  ],
                  "properties": {
                    "active": {
                      "type": "boolean"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "scope": {
                      "type": "string"
                    },
                    "exp": {
                      "type": "integer"
                    },
                    "client_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "Echo the authenticated principal",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Claims summary"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/profile": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "Read the consumer's profile",
        "security": [
          {
            "bearerAuth": [
              "consumer.profile.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Profile"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Me"
        ],
        "summary": "Update the consumer's profile",
        "security": [
          {
            "bearerAuth": [
              "consumer.profile.write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated profile"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/contacts": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "List the consumer's contact channels",
        "security": [
          {
            "bearerAuth": [
              "consumer.profile.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Contacts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Contact"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/addresses": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "List the consumer's addresses",
        "security": [
          {
            "bearerAuth": [
              "consumer.profile.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Addresses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Address"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/documents": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "List the consumer's documents",
        "security": [
          {
            "bearerAuth": [
              "consumer.documents.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Documents (storage_path is never returned)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Document"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/documents/{id}/download": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "Get a short-lived signed URL for a document",
        "security": [
          {
            "bearerAuth": [
              "consumer.documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signed URL"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/consents": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "List pending and historical consent sessions",
        "security": [
          {
            "bearerAuth": [
              "consumer.consent.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Consents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Consent"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/consents/{id}/revoke": {
      "post": {
        "tags": [
          "Me"
        ],
        "summary": "Revoke a consent grant",
        "security": [
          {
            "bearerAuth": [
              "consumer.grants.revoke"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/grants": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "List consent grants the consumer has issued",
        "security": [
          {
            "bearerAuth": [
              "consumer.grants.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Grants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Grant"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/history": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "Activity history for the consumer",
        "security": [
          {
            "bearerAuth": [
              "consumer.history.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "History events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/HistoryEvent"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/notifications": {
      "get": {
        "tags": [
          "Me"
        ],
        "summary": "List notifications addressed to the consumer",
        "security": [
          {
            "bearerAuth": [
              "consumer.notifications.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Notifications",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Notification"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sessions": {
      "post": {
        "tags": [
          "Sessions"
        ],
        "summary": "Create a consent session for a published product",
        "security": [
          {
            "bearerAuth": [
              "sessions.create"
            ]
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sessions/embed": {
      "post": {
        "tags": [
          "Sessions"
        ],
        "summary": "Create an embed session (public client + Origin allowlist)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created embed session"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sessions/{id}": {
      "get": {
        "tags": [
          "Sessions"
        ],
        "summary": "Read a session by id",
        "security": [
          {
            "bearerAuth": [
              "sessions.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sessions/{id}/data": {
      "get": {
        "tags": [
          "Sessions"
        ],
        "summary": "Read the consented data for a session",
        "security": [
          {
            "bearerAuth": [
              "sessions.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session data"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sessions/{id}/revoke": {
      "post": {
        "tags": [
          "Sessions"
        ],
        "summary": "Revoke an issued session",
        "security": [
          {
            "bearerAuth": [
              "sessions.revoke"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "List products",
        "security": [
          {
            "bearerAuth": [
              "partner.products.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Products"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Products"
        ],
        "summary": "Create a product draft",
        "security": [
          {
            "bearerAuth": [
              "partner.products.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Draft product",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/products/{id}": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "Read a product and its versions",
        "security": [
          {
            "bearerAuth": [
              "partner.products.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product"
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Products"
        ],
        "summary": "Save a product draft",
        "security": [
          {
            "bearerAuth": [
              "partner.products.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved draft"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Products"
        ],
        "summary": "Archive a product",
        "security": [
          {
            "bearerAuth": [
              "partner.products.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Archived"
          }
        }
      }
    },
    "/products/{id}/publish": {
      "post": {
        "tags": [
          "Products"
        ],
        "summary": "Publish the current draft",
        "security": [
          {
            "bearerAuth": [
              "partner.products.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published immutable version"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/opportunities": {
      "get": {
        "tags": [
          "Opportunities"
        ],
        "summary": "Search opportunities",
        "security": [
          {
            "bearerAuth": [
              "partner.opportunities.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Opportunity page"
          }
        }
      }
    },
    "/opportunities/{id}": {
      "get": {
        "tags": [
          "Opportunities"
        ],
        "summary": "Read an opportunity timeline",
        "security": [
          {
            "bearerAuth": [
              "partner.opportunities.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Opportunity"
          }
        }
      },
      "patch": {
        "tags": [
          "Opportunities"
        ],
        "summary": "Update an opportunity",
        "security": [
          {
            "bearerAuth": [
              "partner.opportunities.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated opportunity"
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/opportunities/{id}/notes": {
      "post": {
        "tags": [
          "Opportunities"
        ],
        "summary": "Add an internal note",
        "security": [
          {
            "bearerAuth": [
              "partner.opportunities.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created note"
          }
        }
      }
    },
    "/opportunities/{id}/tasks": {
      "post": {
        "tags": [
          "Opportunities"
        ],
        "summary": "Create an internal task",
        "security": [
          {
            "bearerAuth": [
              "partner.opportunities.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created task"
          }
        }
      }
    },
    "/webhook-endpoints": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhook endpoints",
        "security": [
          {
            "bearerAuth": [
              "partner.webhooks.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook endpoints"
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a webhook endpoint",
        "security": [
          {
            "bearerAuth": [
              "partner.webhooks.write"
            ]
          }
        ],
        "responses": {
          "201": {
            "description": "Endpoint and one-time signing secret"
          }
        }
      }
    },
    "/webhook-endpoints/{id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Read a webhook endpoint",
        "security": [
          {
            "bearerAuth": [
              "partner.webhooks.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook endpoint"
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Update or pause a webhook endpoint",
        "security": [
          {
            "bearerAuth": [
              "partner.webhooks.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated webhook endpoint"
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Disable a webhook endpoint",
        "security": [
          {
            "bearerAuth": [
              "partner.webhooks.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Disabled webhook endpoint"
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhook-deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhook deliveries",
        "security": [
          {
            "bearerAuth": [
              "partner.webhooks.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Delivery diagnostics"
          }
        }
      }
    },
    "/webhook-deliveries/{id}/redeliver": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Manually redeliver an event",
        "security": [
          {
            "bearerAuth": [
              "partner.webhooks.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Queued"
          }
        }
      }
    }
  },
  "x-scopes": {
    "consumer.profile.read": "Read the consumer's profile, contacts, and addresses.",
    "consumer.profile.write": "Update the consumer's profile, contacts, and addresses.",
    "consumer.documents.read": "List and download the consumer's documents.",
    "consumer.documents.write": "Upload and delete the consumer's documents.",
    "consumer.grants.read": "List consent grants the consumer has issued.",
    "consumer.grants.revoke": "Revoke a consent grant the consumer has issued.",
    "consumer.history.read": "Read activity history for the consumer.",
    "consumer.notifications.read": "Read notifications addressed to the consumer.",
    "consumer.notifications.write": "Mark notifications as read for the consumer.",
    "consumer.consent.read": "Inspect pending consent sessions for the consumer.",
    "consumer.consent.respond": "Approve or deny a pending consent session.",
    "partner.products.read": "Read the client's products and immutable versions.",
    "partner.products.write": "Create drafts and publish or archive products.",
    "partner.opportunities.read": "Search and read the client's opportunities.",
    "partner.opportunities.write": "Update opportunities, notes, tasks, and outcomes.",
    "partner.webhooks.read": "Read webhook endpoints and delivery diagnostics.",
    "partner.webhooks.write": "Manage webhook endpoints and redeliver events.",
    "sessions.create": "Create application sessions for a client.",
    "sessions.read": "Read application sessions and consented data.",
    "sessions.revoke": "Revoke an application session."
  }
}