overlay: 1.0.0
info:
  title: Citizens Authorize (IDP v1.0) API enrichment overlay
  version: 1.0.0
  x-generated: '2026-09-05'
  x-method: generated
  x-source: API Evangelist enrichment pass 2026-09-05; every value is read from the harvested contract
    itself or from a Citizens-published page named in the action description.
extends: citizens-financial-group-authorize-openapi.yml
actions:
- target: $.info
  description: Record the harvest provenance and the portal page the contract was read from.
  update:
    x-apis-io-harvested: '2026-09-05'
    x-apis-io-source: https://developer.citizensbank.com/product/88/api/73
    x-apis-io-environment: production
- target: $.paths['/revoke'].post
  description: Supply a stable identifier for the only operation in this contract; the published contract
    declares none.
  update:
    tags:
    - Identity
    x-apis-io-operation-id: revokeToken
    x-apis-io-operation-id-source: assigned by API Evangelist; the published contract declares none
- target: $
  description: Record the discovery gap on the identity surface. The contract describes the Citizens IDP but
    publishes only the revoke endpoint - the token endpoint that actually issues the credential is documented
    solely in the PDF user guides, and no OAuth or OIDC discovery document is served on any Citizens host.
  update:
    x-identity-surface:
      declared-operations:
      - POST /revoke
      undeclared-but-required:
      - name: token endpoint
        production: https://apis.citizensbank.com/as/token.oauth2
        sandbox: https://sandboxapis.citizensbank.com/as/token.oauth2
        source: https://developer.citizensbank.com/content/qut/CitizensPaymentAPIUserGuide.pdf section 3.1.3
      discovery-documents:
        openid-configuration: not served (probed 2026-09-05 on every Citizens host)
        oauth-authorization-server: not served (probed 2026-09-05 on every Citizens host)
        see: well-known/citizens-financial-group-well-known.yml
      grant-type: client_credentials with a private_key_jwt client assertion over mTLS
      see: authentication/citizens-financial-group-authentication.yml
    x-error-contract-gap:
      declared-status-codes:
      - '200'
      note: No 4xx or 5xx response is declared on the revoke operation.