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 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 the authenticated user consent dashboard records.
GetCdrConsent
Returns one owned consent plus receipts and audit events.
WithdrawCdrConsent
Blocks collection, disables token grants, deletes redundant data 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.
| 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; 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. |
| 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; 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 and deletion-election changes are audited.
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.
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 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, 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-run-readiness-gates.mjs --environment prod --public-base-url https://api.pfinance.dev --repeat 3node 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 3Submission 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