Citizens Financial Group Authentication

generated: '2026-09-05'
method: searched
source: >-
  https://developer.citizensbank.com/content/qut/CitizensPaymentAPIUserGuide.pdf (v1.3, updated
  2025-12-11) section 3 "AUTHENTICATION"; the same section appears in the Account Transfer (v1.0,
  2026-05-29), Account Validation (v1.6, 2026-04-30) and Information Reporting (v1.6, 2026-07-22)
  user guides. Scheme detail derived from the harvested specs in openapi/.
docs: https://developer.citizensbank.com/content/qut/CitizensPaymentAPIUserGuide.pdf
provider: Citizens Financial Group
providerId: citizens-financial-group

summary:
  model: >-
    Two-legged OAuth 2.0 client-credentials with a private_key_jwt client assertion over mutual TLS,
    stated by Citizens to follow the Financial-grade API (FAPI) Security Profile 1.0 - Part 2:
    Advanced. Every commercial-banking call additionally carries an IBM API Connect client id header
    (X-IBM-Client-Id) issued by the developer portal, and a required x-fapi-trace-id correlation
    header. The FDX account/statement surface and the ATM/branch locator surface are key-header only
    in the published contracts.
  types:
    - oauth2
    - apiKey
    - mutualTLS
  api_key_in:
    - header
  oauth2_flows:
    - clientCredentials

token_endpoints:
  - environment: production
    url: https://apis.citizensbank.com/as/token.oauth2
    source: CitizensPaymentAPIUserGuide.pdf section 3.1.3
  - environment: sandbox
    url: https://sandboxapis.citizensbank.com/as/token.oauth2
    source: CitizensPaymentAPIUserGuide.pdf section 3.1.3
  - environment: production (JWT `aud` claim value)
    url: https://pf-fam.citizensbank.com
    source: CitizensPaymentAPIUserGuide.pdf section 3.1.2
  - environment: sandbox (JWT `aud` claim value)
    url: https://pf-fam-sb.internal.citizensbank.com
    source: CitizensPaymentAPIUserGuide.pdf section 3.1.2
  - environment: as published in the OpenAPI securitySchemes
    url: https://pf-fam.internal.citizensbank.com/as/token.oauth2
    source: openapi/_original/citizens-payments-v3.json
    note: >-
      The tokenUrl carried in the specs' oauth2 securityScheme names an .internal. host that does not
      resolve publicly; the user guides publish apis.citizensbank.com / sandboxapis.citizensbank.com
      as the callable token endpoints. Recorded as-published, not reconciled.

flow:
  name: OAuth 2.0 JWT client assertion (private_key_jwt) over mTLS
  grant_type: client_credentials
  client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  steps:
    - Client and Citizens authorization server present certificates validated against a shared CA (mTLS).
    - Client builds a JWT assertion with iss = sub = Client ID from the developer portal, aud = the
      token endpoint URL, exp <= 3600 seconds, and a unique jti to prevent replay.
    - JWT is signed with the client private key (RS256); the client hosts a JWKS URL exposing the
      public key for Citizens to verify.
    - Client POSTs client_id, grant_type, client_assertion_type, client_assertion and scope to the
      token endpoint over the mTLS channel.
    - Citizens validates the assertion and the client certificate and issues a Bearer access token.
    - Client calls the resource server with the Bearer token plus X-IBM-Client-Id and x-fapi-trace-id.
  jwt_claims:
    - iss (Client ID from the developer portal)
    - sub (same as iss)
    - aud (token endpoint URL)
    - exp (must not exceed 3600 seconds)
    - jti (unique, to prevent replay)
  signing_algorithm: RS256
  client_key_distribution: JWKS endpoint hosted by the client, or a key store supplied at onboarding
  mutual_tls: true
  ip_allowlisting: >-
    Client IPs are provisioned by the Citizens Implementation Manager during onboarding
    (CitizensPaymentAPIUserGuide.pdf section 2).

schemes:
  - name: OAuth2
    type: oauth2
    flow: clientCredentials
    applies_to:
      - Payments
      - Account Transfer
      - Account Validation
      - Information Reporting
    sources:
      - openapi/citizens-financial-group-payments-openapi.yml
      - openapi/citizens-financial-group-account-transfer-openapi.yml
      - openapi/citizens-financial-group-account-validation-openapi.yml
      - openapi/citizens-financial-group-information-reporting-openapi.yml
  - name: client-id
    type: apiKey
    in: header
    parameter: X-IBM-Client-Id
    description: >-
      IBM API Connect application client id (called "API Key" in the portal). Retrieved from
      Apps > your application > Subscriptions in the developer portal.
    applies_to:
      - Payments
      - Account Transfer
      - Account Validation
      - Information Reporting
  - name: x-fapi-financial-id
    type: apiKey
    in: header
    parameter: x-fapi-financial-id
    description: Identifies the desired financial institution or partners.
    applies_to:
      - Accounts (FDX v1.0 and v2.1)
      - Statements (FDX v1.0 and v2.1)
  - name: x-client-id
    type: apiKey
    in: header
    parameter: x-client-id
    description: Identifies the desired financial institution or partners.
    applies_to:
      - Authorize (IDP v1.0 / v2.0)
  - name: Partner Id
    type: apiKey
    in: header
    parameter: Partner-ID
    description: Used for differentiating the registered vendors/partners.
    applies_to:
      - ATM Locator
      - Branch Locator

required_headers:
  - name: x-fapi-trace-id
    required: true
    max_length: 36
    description: Unique request id (UUID) for each request to make it traceable.
  - name: x-fapi-channel-id
    required: false
    max_length: 20
    description: Distinguishes communication channels or data streams within a client system.
  - name: Authorization
    required: true
    description: OAuth 2.0 Bearer access token.
  - name: X-IBM-Client-Id
    required: true
    description: Developer-portal application client id.
  - name: requestid
    required: false
    max_length: 36
    description: >-
      Consumer-assigned request identifier echoed back as requestId for tracking, logging and
      correlation (Payments user guide 5.1.2 / 5.1.5).

onboarding:
  process: >-
    Access is not self-service. A Citizens Implementation Manager runs a kickoff, collects authorized
    security contacts, the client IPs to allowlist, the public key for the mTLS certificate and a
    private key via JWKS endpoint or key store. All testing happens in the sandbox; message signing
    and sandbox sign-off are required before a production date is agreed and the application is
    registered by the Citizens API team.
  portal_roles:
    - Owner - manages organization settings, applications and credentials; may invite additional users.
    - Administrator - same permissions as owner.
    - Developer - view/manage organization settings, application settings/credentials, subscriptions, analytics.
    - Viewer - view-only access to organization, applications and analytics.
  source: https://developer.citizensbank.com/content/qut/CitizensPaymentAPIUserGuide.pdf

notes:
  - No public OpenID Connect discovery document is served; /.well-known/openid-configuration on every
    Citizens host probed on 2026-09-05 either 404s or returns the portal search page (see well-known/).
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com