Skip to main content

Implementation Guides

Service User Implementation Guide​

1. Client Responsibilities​

  • Generate PKCE (S256) according to RFC7636 (code_verifier length, allowed characters, hashing rules).
  • Implement PAR using required headers (X‑Correlation-ID, X‑CorAPI‑Target-ID, etc.).
  • Store access_token, refresh_token, and grant_id securely.
  • Always include code_verifier in the token exchange.
  • Request appropriate scopes.

2. Grant Management Requirements​

  • Know when to send merge versus replace.
  • Apply additive-only logic for merge.
  • Do not send grant_id on create.
  • Persist grant_id long-term (it is stable across token cycles).
  • If grant_management_action is omitted, default is create.

3. Token Handling Requirements​

  • Implement refresh token lifecycle logic.
  • Detect expired tokens (e.g., 401 returned to SU after SP validation via bLink).
  • Apply correct retry behavior.

4. Error Handling​

  • Understand OAuth2 error semantics (invalid_grant, invalid_request, invalid_scope, etc.).
  • Identify which errors are retriable vs. non‑retriable.
  • Know when a new consent authorization must be initiated.

5. Migration Relevance​

  • For CF2 clients, the transition to Consent 3.0 is automatic. As soon as the client makes its first token refresh against the Consent 3.0 endpoint, the Service Provider will return a grant_id.
  • CaaS clients do require migration** to convert PermissionIds into OAuth tokens.

Service Provider Implementation Guide​

1. API-Level Requirements​

  • Implement the PAR endpoint with correct validation and error handling.
  • Support PKCE S256 only.
  • Reject authorization requests missing PKCE parameters.
  • Validate code_verifier at the token endpoint.

2. Grant Management Requirements​

  • Store grant objects (grant_id, scope/account sets, timestamps, etc.).
  • Implement merge without deleting existing scopes or accounts.
  • Implement replace with full overwrite semantics.
  • Return the same stable grant_id for the same grant in every token response.
  • Single‑issuance behavior: one active grant → always the same grant_id.
  • Multi‑issuance behavior: multiple active grants supported simultaneously.

3. Token Response Requirements​

  • MUST include: access_token, token_type, expires_in, grant_id.
  • OPTIONAL include: refresh_token, scope.
  • MUST return the same grant_id for the same consent across refresh cycles.

4. Error Handling Requirements​

  • Follow OAuth2 error semantics for PAR.
  • Follow OAuth2 error semantics for the token endpoint.
  • Define behavior when grant_management_action is malformed.
  • Define behavior on invalid or unknown grant_id.

1. Token Forwarding vs. Token Substitution​

  • CaaS-origin clients:
    bLink uses SP-side tokens (substitution) when forwarding the request.
  • CF2-origin clients:
    bLink forwards the SU access token unchanged (pure relay).

2. Directory Updates​

  • Maintain additional capability flags (e.g., concurrent_grants_supported).

3. Support & Testing​

  • Provide testing facilities and simulator support.
  • Ensure a smooth transition for ecosystem participants.

Implementation Readiness Checklist​

For Service Users​

  • Implement PAR
  • Implement PKCE S256
  • Store access_token, refresh_token, and grant_id
  • Implement refresh logic
  • Optionally implement Grant Management actions (merge, replace)
  • Handle OAuth errors correctly
  • Migrate PermissionIds (CaaS only)

For Service Providers​

  • Implement PAR endpoint
  • Implement PKCE S256 validation
  • Issue consistent grant_id values
  • Support merge and replace
  • Maintain stable token response behavior
  • Provide correct OAuth error semantics
Last updated on