Open Banking API
CDR authentication and authorisation reference
This draft reference covers the PFinance Consumer Data Right API surfaces for Open Banking consent, OAuth/JARM callbacks, data-holder revocation, user-owned Connect-RPC access, and OIDC-protected lifecycle workers.
Authentication Layers
| Layer | Caller | Mechanism | Authorisation control |
|---|---|---|---|
| Consumer auth | PFinance browser and app users | Firebase bearer token | Connect-RPC APIs authenticate the user and enforce consent ownership before returning CDR records. |
| Programmatic auth | User-created Pro API clients | X-API-Key | API tokens are hashed at rest, checked on every request, rejected immediately after expiry or revocation, and blocked from token-management RPCs. |
| CDR protocol auth | CDR Register and Data Holders | SSA, DCR, mTLS, PAR, PKCE, PS256 private_key_jwt, signed/encrypted JARM, and CDR Arrangement JWT | Used for registration, consent authorisation, token exchange, resource collection, and arrangement revocation. |
| Operations auth | Cloud Scheduler | Google OIDC bearer token | Consent expiry, token grant expiry/refresh, redundant-data deletion, and outbound revocation jobs require a configured audience and scheduler service-account email. |
Public CDR Endpoints
These routes are outside product-user auth because they are called by data holders, metadata consumers, or public conformance checks.
| Endpoint | Methods | Purpose |
|---|---|---|
| /cdr/openapi.json | GET, HEAD | Public OpenAPI 3.1 contract for public CDR, Connect-RPC, and lifecycle auth surfaces. |
| /cdr/jwks | GET, HEAD | Public data-recipient software-product signing keys. |
| /.well-known/jwks.json | GET, HEAD | Compatibility JWKS alias for data-holder metadata consumers. |
| /cdr/oauth/callback | GET, POST | Data-holder OAuth/JARM callback for consent activation. |
| /cdr/arrangements/revoke | POST | Data-holder initiated arrangement revocation. |
| /arrangements/revoke | POST | Standards-compatible revocation alias. |
Authenticated Open Banking APIs
Connect-RPC procedures are exposed as /pfinance.v1.FinanceService/<RpcName>. Each procedure requires Firebase bearer auth or a valid PFinance API token, then checks user ownership before reading or mutating CDR data.
ListCdrDataHolders
Lists active data-holder brands available for the Open Banking connection flow.
CreateCdrConsentDraft
Creates the local single-data-holder consent record, selected scopes, duration, deletion election, and receipt evidence.
StartCdrAuthorisation
Starts PAR/PKCE authorisation using holder-specific DCR client identity and signed request material.
ListCdrConsents
Returns authenticated user consent dashboard records plus persistent collection summaries derived from holder request logs.
GetCdrConsent
Returns one owned consent plus receipts and audit events.
WithdrawCdrConsent
Blocks collection, disables token grants, deletes local CDR account, balance, transaction, and CDR-provenanced expense records when elected, and schedules holder revocation.
UpdateCdrDeletionElection
Updates the consumer redundant-data election for an owned consent.
SyncCdrConsentData
Refreshes tokens when needed and collects authorised account, balance, and transaction data.
ListCdrAccounts, ListCdrBalances, ListCdrTransactions
Lists collected records scoped to the authenticated consent owner.
Auth Management APIs
Token-management RPCs are documented in the OpenAPI contract with Firebase bearer security only. A request authenticated through X-API-Key is rejected before any token list, mint, or revoke operation runs.
CreateApiToken
Creates a Pro user API token and returns the raw token once. Requires an interactive Firebase/local user session.
ListApiTokens
Lists token metadata for the authenticated Pro user. API-token-authenticated calls are rejected.
RevokeApiToken
Revokes one owned API token. Revocation is checked on the next request.
Full Auth Process Matrix
These are the implemented authentication and authorisation processes that must be evidenced before ADR submission and CTS. The same matrix is also exposed in the OpenAPI extension x-cdr-authentication-flows. Protocol credential schemes are exposed in x-cdr-protocol-security-schemes. Collection scope rules are exposed in x-cdr-scope-authorization-matrix.
| Process | Entrypoint | Credentials | Authorisation gates | Evidence |
|---|---|---|---|---|
| PFinance user auth | Connect-RPC finance and Open Banking APIs | Firebase bearer token or X-API-Key | UID, user_id, consent_id, token ownership, and CDR data ownership are enforced before reads or mutations. | Auth interceptor tests, API-token revocation tests, service ownership tests, public-edge fail-closed smoke. |
| API token management | CreateApiToken, ListApiTokens, and RevokeApiToken | Firebase bearer token or local development auth | Interactive Pro user session required; API-token-authenticated calls are rejected to prevent token chaining. | Service-level token management authorization tests and OpenAPI contract coverage. |
| Dynamic Client Registration | cdr-dcr-register and data-holder /register | Register token, SSA, mTLS certificate, PS256 registration JWT | SSA claims, software product, redirect URI, JWKS URI, recipient base URI, and holder status must validate. | Register/DCR unit tests, mTLS fake-holder smoke, persisted redacted registration evidence. |
| Consent authorisation start | CreateCdrConsentDraft and StartCdrAuthorisation | Authenticated user, holder DCR client ID, PKCE S256, nonce, PAR, signed request object | Consent owner only; exactly one holder active; scopes, duration, policy, deletion election, and DCR client state valid. | Consent service tests, PAR tests, cdr-cts-smoke, readiness-gates output. |
| OAuth callback and token exchange | /cdr/oauth/callback | Signed or encrypted JARM, state hash, PKCE verifier, private_key_jwt, signed ID token | Callback must match the stored consent session, holder, nonce, audience, and single-use state. | JARM/JWE tests, token client tests, callback service tests, source and running-service smoke. |
| Holder resource access | SyncCdrConsentData and list CDR data RPCs | mTLS, bearer access token, x-fapi-interaction-id, token vault | Consent must be active, collection unblocked, required scopes present, and token grant active. | Banking client tests, sync service tests, fake-holder collection smoke, redacted request logs, and persistent collection-summary smoke/readiness flags. |
| Arrangement revocation | /cdr/arrangements/revoke and /internal/cdr/jobs/revoke-arrangements | Holder bearer JWT, CDR Arrangement JWT, or ADR private_key_jwt outbound | Arrangement must map to the holder and local consent; outbound runs only for consumer-withdrawn arrangements. | Inbound revocation tests, outbound client tests, Scheduler execution logs, smoke evidence. |
| Lifecycle workers | /internal/cdr/jobs/expire-consents, /internal/cdr/jobs/expire-token-grants, /internal/cdr/jobs/refresh-token-grants, /internal/cdr/jobs/delete-redundant-data, and /internal/cdr/jobs/revoke-arrangements | Google OIDC bearer token | Audience and scheduler service-account email must match runtime configuration. | Server internal-job tests, Terraform Scheduler jobs, authenticated Cloud Scheduler and Cloud Run HTTP 200 logs. |
Authorization Rules
ListCdrDataHolders
Any authenticated user; no user CDR records are returned.
CreateCdrConsentDraft
Authenticated UID must match userId or userId must be omitted; exactly one active holder, scope, duration, policy, and deletion election are validated.
StartCdrAuthorisation
Consent owner only; consent must be draft; holder metadata, DCR client registration, signing, and PAR config must be usable.
Get/List/Withdraw/Update CDR consents
Consent owner only; state transitions, collection-summary projections, and deletion-election changes are audited/scoped to the caller.
SyncCdrConsentData
Consent owner only; active consent, unblocked collection, scopes, token vault, and active grant are required.
ListCdrAccounts/Balances/Transactions
Consent owner only; records are scoped by consentId and userId.
Create/List/Revoke API tokens
Interactive authenticated Pro user only; API-token-authenticated calls are rejected; token quota and ownership are enforced.
Scope Authorization Matrix
OpenAPI exposes these collection-time CDR scope gates in x-cdr-scope-authorization-matrix.
CreateCdrConsentDraft
Selected consent scopes
Requested scopes must be explicit, supported, and recorded in the consent receipt before authorisation starts.
SyncCdrConsentData: accounts
CDR_SCOPE_BANK_ACCOUNTS_BASIC_READ or CDR_SCOPE_BANK_ACCOUNTS_DETAIL_READ
Account and balance collection fails closed before holder calls when account scopes are absent.
SyncCdrConsentData: transactions
CDR_SCOPE_BANK_TRANSACTIONS_READ
Transaction collection requires this scope when includeTransactions is true; smoke/readiness evidence proves missing-scope requests fail before token-vault or holder transaction calls.
ListCdrAccounts/Balances/Transactions
Collection-time scope evidence
List APIs are consent-owner scoped and rely on the originating consent scope checks.
Data Lifecycle Controls
CDR data remains traceable from holder collection through any product projection. Redundant-data deletion evidence proves both raw CDR records and CDR-provenanced expenses were removed for the withdrawn consent.
Raw CDR records
Accounts, balances, and transactions stay in the CDR store with consent, holder, account, request, and raw-hash provenance.
Collection summaries
ListCdrConsents returns collectionSummaries with collected data types, latest collection timestamp, holder attribution, latest status, and request success/failure counts derived from CdrDataRequestLog.
CDR-provenanced expenses
Product expenses derived from CDR transactions carry cdrConsentId, cdrDataHolderBrandId, cdrAccountId, cdrTransactionId, and cdrRawHash.
Redundant-data deletion
Withdrawals with DELETE_REDUNDANT_DATA delete raw CDR records and matching CDR-provenanced expenses, remove them from product search, then record a redacted tombstone with derived_expenses_deleted.
Readiness evidence
Source-level and running-service smoke reports must show collection_summary_persisted, collection_summary_latest_collected_at_present, collection_summary_holder_recorded, deletion_tombstone_recorded, cdr_derived_expenses_after_withdrawal: 0, cdr_derived_expense_search_cleanup_verified, cdr_derived_expense_search_results_after_withdrawal: 0, and a positive derived_expenses_deleted count.
Credential Handling
Firebase ID token
Verified by backend interceptor; raw token is not persisted.
PFinance API token
Generated once, stored as SHA-256 hash, expiry and revocation checked every request.
Register token and SSA
Loaded from protected runtime sources; raw token, SSA, and registration JWT are redacted from evidence.
mTLS certificate and private key
Loaded from Secret Manager or mounted secret files after PKI issuance; private key material is never committed.
Software signing key
Cloud KMS PS256 signer; public JWK is served by /cdr/jwks.
JARM decryption key
Secret Manager version loaded only through the approved key ceremony; current production secret version remains gated.
Access and refresh tokens
Encrypted before persistence; hashes are used for identifiers and evidence.
Scheduler OIDC token
Validated for exact audience and scheduler service account before worker execution.
Protocol Security Schemes
The OpenAPI extension x-cdr-protocol-security-schemesenumerates the non-browser CDR credentials and controls that must be evidenced before production activation.
Register bearer
Register metadata sync and SSA retrieval use protected bearer credentials from runtime secret sources.
Data Holder mTLS
DCR, token, resource, and revocation calls use official data-holder transport credentials once issued.
private_key_jwt
Cloud KMS PS256 signing backs DCR, PAR, token exchange, and outbound revocation assertions.
PAR + PKCE S256
Authorisation start stores hashes for state, nonce, and request URI while the verifier stays server side.
JARM JWS/JWE
Callbacks validate signed or encrypted holder responses before token exchange and consent activation.
CDR Arrangement JWT
Holder revocation validates bearer and arrangement JWTs, replay IDs, and local arrangement ownership.
Scheduler OIDC
Lifecycle workers accept only the configured Google OIDC audience and scheduler service account.
Auth Evidence Matrix
OpenAPI exposes the same reviewer checklist in x-cdr-auth-evidence-matrix, linking each authentication process to local validation evidence, redaction controls, and the external approval gate that must close before portal submission.
| Process | Local evidence | External gate |
|---|---|---|
| PFinance user auth | Local auth/service tests and running-service smoke | SECURITY_COMPLIANCE_APPROVAL |
| API token management | API-token management authorization tests and OpenAPI contract tests | SECURITY_COMPLIANCE_APPROVAL |
| Dynamic Client Registration | DCR unit tests, mTLS fake-holder smoke, and cdr-cts-smoke | PRODUCTION_MTLS_REGISTER_CREDENTIALS |
| Consent authorisation | PAR/PKCE service tests, source smoke, and Ginkgo compliance evidence | OFFICIAL_CTS_EVIDENCE |
| OAuth callback and token exchange | JARM/JWE callback tests, token client tests, and running-service smoke | OFFICIAL_CTS_EVIDENCE |
| Holder resource access | Banking client tests, sync service tests, and scope negative-case smoke | SCHEDULE_2_SECURITY_SIGNOFF |
| Arrangement revocation | Inbound/outbound revocation tests and retry/idempotency smoke | PRODUCTION_MTLS_REGISTER_CREDENTIALS |
| Lifecycle workers | Internal job auth tests and live Scheduler execution evidence | FINAL_REGISTER_PORTAL_EXPORTS |
Protocol Flows
- Dynamic Client Registration uses CDR Register SSA material, mTLS transport, and signed registration JWTs before holder-specific client IDs are used.
- Consent authorisation uses authenticated product users, consent draft validation, PAR where exposed by the holder, PKCE S256, nonce binding, and signed request objects.
- Callback processing accepts signed or signed-then-encrypted JARM, validates state/session expiry/single-use, verifies replay IDs, exchanges codes with private_key_jwt, and validates ID token nonce/audience/issuer/expiry.
- Resource access decrypts token material only inside the backend, uses bearer access tokens with CDR headers, writes redacted request evidence, projects collection summaries for the dashboard, and gates collection on consent state, scopes, and token grant state.
- Revocation supports both data-holder initiated revocation and ADR-to-data-holder reconciliation after consumer withdrawal.
Validation Evidence
These checks back the current implementation. Official Register credentials, mTLS certificates, holder execution, CTS evidence, and legal/security approvals remain external submission gates.
go test ./internal/service -run TestApiTokenManagementRejectsApiTokenAuthenticatedCaller -count=1go test ./internal/cdr/... -count=1go test ./cmd/cdr-cts-smoke -count=1go run ./cmd/cdr-cts-smokego run ./cmd/cdr-cts-smoke --running-servicego run ./cmd/cdr-cts-smoke --public-base-url https://api.pfinance.devmake cdr-compliance-e2enode scripts/cdr-ginkgo-external-evidence-workflow.test.mjsnode scripts/cdr-ginkgo-portal-submission-workflow.test.mjsnode scripts/cdr-generate-data-environment-evidence.mjs --environment prodnode scripts/cdr-run-readiness-gates.mjs --environment prod --public-base-url https://api.pfinance.dev --repeat 3node scripts/cdr-external-evidence-status.mjs <assembled-package> --external-evidence-manifest <external-evidence-manifest.json> --evidence-root <external-evidence-root> --report <external-evidence-workspace>/EXTERNAL_EVIDENCE_STATUS.mdnode scripts/cdr-production-readiness-validation.mjs --environment prod --public-base-url https://api.pfinance.dev --external-evidence-manifest <external-evidence-manifest.json> --external-evidence-root <external-evidence-root> --repeat 3node scripts/cdr-export-portal-submission-bundle.mjs output/cdr-production-readiness-validation/<timestamp>-prod <portal-submission-output>node scripts/cdr-validate-portal-submission-bundle.mjs <portal-submission-output>node scripts/cdr-final-submission-preflight.mjs --assembled-package <assembled-package> --production-readiness output/cdr-production-readiness-validation/<timestamp>-prod --portal-submission-bundle <portal-submission-output> --external-evidence-manifest <external-evidence-manifest.json> --external-evidence-root <external-evidence-root>Submission Status
The API, auth, and lifecycle foundations are implemented and testable. Production activation still requires official Register onboarding, software-product approval, PKI/mTLS material, data-holder DCR execution, CTS validation, and approved public policy/support artefacts.
Support and contact channels