Skip to main content

Grant Management

Consent 3.0 introduces a minimal, FAPI‑aligned Grant Management model with a controlled set of lifecycle operations.
This enables Service Users to update existing consents without requiring a full re‑authorization while keeping initial implementation overhead low.

Grant Management provides:

  • A standardized representation of a consent grant, independent of token rotation
  • Lifecycle operations (create, merge, replace) to evolve an existing consent
  • Compatibility with both single‑issuance and multi‑issuance Service Providers

Grant Identifier (grant_id)​

Every token response in Consent 3.0 MUST include a grant_id.
This identifier:

  • Remains stable for the lifetime of the consent
  • Allows SUs to reference, update, or replace an existing grant
  • Acts as an anchor for future capabilities (e.g., event notifications)
  • Supports both SP types:
    • Single‑issuance SPs reuse the same grant_id across updates
    • Multi‑issuance SPs may hold several active grant_ids

Service Provider Requirements​

All Service Providers MUST implement the following minimum Grant Management capabilities:

Replace (mandatory)​

  • Fully replace the existing grant with a new set of scopes/accounts.
  • Required when scopes or accounts are removed.

Merge (mandatory)​

  • Add new scopes/accounts to an existing grant.
  • Additive only - scopes/accounts omitted in a merge request MUST NOT be removed.

Return grant_id in every token response (mandatory)​

  • The value MUST remain stable for the entire lifespan of the grant.

Service User Requirements​

General​

  • grant_management_action is optional
    • If omitted → defaults to create.

When performing an update​

  • For merge or replace:
    • grant_id MUST be included in the request
  • For create:
    • grant_id MUST NOT be included
  • merge operations MUST be treated as additive only

This ensures Service Users that do not require Grant Management can integrate with minimal complexity, while advanced SUs can build richer consent logic.

Grant Management Action Matrix​

ActionSP Required?SU Required?grant_id in RequestBehavior / Allowed ChangesTypical Use Case
createYesOptionalMUST NOT be sentCreate a new grantInitial consent creation
mergeYes (mandatory)OptionalrequiredAdd scopes/accounts - no removalsAdd account, add AIS scope, extend access
replaceYes (mandatory)OptionalrequiredFull replacement - add and remove scopesStructural change, remove scope, mandate update

Examples​

If the Service User does not send any Grant Management parameters, the Service Provider MUST treat this as a create action.

Request example:

grant_management_action omitted

Outcome:

  • A new grant is created.
  • A new grant_id is returned in the token response.
  • SP associates the consent with this new grant_id.

2. Scope / Account Extension (merge)​

A merge action is used to add scopes or accounts to an existing grant.
It is additive only: any scopes not included in the request MUST remain active.

Request example:

{
"grant_management_action": "merge",
"grant_id": "<existing-grant-id>",
"scope": "urn:blink:xs2a:ais urn:blink:xs2a:pss:write urn:blink:extra:scope"
}

Outcome:

  • SP adds new scopes/accounts.
  • SP keeps existing scopes not listed in the merge request.
  • SP returns the same grant_id.

3. Full Replacement (replace)​

A replace action instructs the SP to fully overwrite the existing grant with the scope/accounts provided.

Request example:

{
"grant_management_action": "replace",
"grant_id":"<existing-grant-id>",
"scope": "urn:blink:xs2a:ais>"
}

Outcome:

  • SP replaces the entire grant with the new scope set.
  • Removed scopes/accounts are revoked.
  • SP continues using the same grant_id (the grant itself persists, but its content is replaced).

4. Single‑Issuance Service Provider​

Single‑issuance SPs maintain exactly one active consent per SU and therefore reuse the same grant_id for all update operations.

Behavior:

  • create → creates the one active grant
  • merge → updates the same grant, only adding scopes
  • replace → updates the same grant, replacing the scope set
  • SP never issues a second grant concurrently
  • SP always returns the same grant_id

Example:

{
  grant_id : "11111111-1111-1111-1111-111111111111"
}

This value will be returned for every token response, regardless of merges or replacements.

Summary​

  • create → no GM parameters; new grant_id
  • merge → grant_id required; additive only
  • replace → grant_id required; full overwrite
  • single‑issuance SP → always the same grant_id, regardless of update type
Last updated on