The Government has restated its commitment to delivering pensions dashboards in a written statement.
Technical standards
Contents
The technical standards are what data and dashboard providers will use to interface with the central technical architecture and/or each other. This includes the connectivity mechanisms; protocols for authorising the sharing of information; the methodology for the generation of pension identifiers, tokens, globally unique identifiers used in ecosystem transactions; and the rules for registration of pension identifiers for pensions found.
Further technical documentation to accompany the technical standards will be released at a later date.
Draft version 1.1
All PDP standards are published as ‘draft’ until approved by the Secretary of State for Work and Pensions. Find out more about PDP’s approach to standards governance.
PDP recommends schemes and providers align with the current version whilst preparing for connection. This version was developed following industry consultation and review by PDP volunteer participants.
PDP may make further changes before seeking formal approval. Only necessary changes will be considered and we will work with industry to understand potential impacts.
Changelog
Refer to the changelog for updates since the last publication.
Corrections log (errata)
Refer to the corrections log (errata) for known issues and corrections for the current version. These corrections will be included in future versions.
Back to topDownloads
Download the APIs and schemas related to the technical standards.
Download PDP_Technical_Standards_APIs_And_Schemas v1.1.zip
Back to topIntroduction
Background
1. Pensions dashboards are apps, websites or other tools which help individuals view information about their multiple pensions in one secure place online, at a time of their choosing. They bring together information on all a user’s (in-scope) pensions, including their State Pension, as well as any occupational and personal pensions. This supports individuals’ engagement with their pensions and their planning for retirement.
2. The Money and Pensions Service (MaPS) set up the Pensions Dashboards Programme (PDP) in 2019 to design and build the central digital architecture (CDA) and services that make pensions dashboards possible. PDP are also responsible for the supporting governance framework, service design and operating model for the pensions dashboards ecosystem.
3. The pensions dashboards ecosystem enables millions of individuals to connect with their pensions information through multiple dashboards across thousands of pension providers and schemes. Find out more about the pensions dashboards ecosystem and its components.
4. MaPS is responsible for operating its own non-commercial, pensions dashboard as a public service.
Purpose
5. These technical standards are issued by the Money and Pensions Service (MaPS) under delegated powers given by the Pensions Dashboards Regulations 2022 and the Pensions Dashboards Regulations (Northern Ireland) 2023 (referred to hereafter as ‘Regulations’) and the FCA’s Pensions Schemes (Information to Dashboards) Instrument 2022/38 rules for pension providers (hereafter ‘Rules’).
6. The technical standards provide the basis for interoperability across the pensions dashboards ecosystem. They provide a common set of connectivity mechanisms and interfacing rules for pension providers and schemes and dashboard providers, determining how parties are to interact with and communicate with the central digital architecture and each other.
7. The technical standards therefore cover:
- connectivity mechanisms
- protocols for authorizing the sharing of information
- the methodology for the generation of pension identifiers, tokens, globally unique identifiers used in ecosystem transactions
- the rules for registration of pension identifiers for pensions found
- definitions of APIs to be used by ecosystem participants
- details of how the APIs must be used during the expected functioning of the ecosystem
8. The technical standards facilitate pension providers’ and schemes’ and pensions dashboard service providers’ compliance.
Areas for future inclusion
9. There are a number of areas of functionality that will be addressed in later versions of the technical standards, namely:
- standards that apply only to pension dashboard providers
- mechanism to enable refresh of PAT tokens to allow pension providers and schemes to manage resources that they have registered
- PAT refresh notifications issued by the CDA to the pension providers or schemes
- general error response formats and codes
Audience
10. These standards apply legally to the trustees or managers of occupational pension schemes (pension schemes), the managers of stakeholder and personal pension schemes (pension providers), and to qualifying pensions dashboards services connected to, or required to connect to, the pensions dashboards ecosystem.
11. Where pension providers and schemes or where pensions dashboard services connect to the ecosystem using a third-party supplier, such as a third-party administrators or software providers, the third parties will apply the technical standards on behalf of their client pension providers and schemes or pensions dashboard providers. We expect much of the implementation of our standards will be undertaken by these third parties on behalf of multiple clients. A pension provider or scheme or a pensions dashboard provider connecting via an already-connected third party will use the third party’s processes to meet the standards. However, as the standards apply to the pension provider or scheme or the dashboard provider, the latter are responsible for compliance with them, even if implementation is delegated to a third party. When we refer to pension providers and schemes and dashboard providers, this includes any of these third parties.
Jurisdiction
12. These standards apply to all United Kingdom pension providers subject to the dashboard duties in the FCA Rules, all United Kingdom schemes subject to the dashboard duties in the DWP Regulations, and all qualifying pensions dashboard service providers meeting the conditions in the DWP Regulations.
Other guidance
13. These standards should be read in conjunction with the other PDP standards (data standards, code of connection, reporting standards).
Use and evidence
14. Standards are mandatory requirements and, therefore, compliance by pension providers and schemes and by pensions dashboard service providers is compulsory.
15. Standards may be admitted in any proceedings relevant to pension providers and schemes and pensions dashboard providers’ compliance with their duties. This applies to the obligations owed by any other party. For example, a pension provider’s sponsoring employer or administrator. The body hearing the proceedings, including the FCA or The Pensions Regulator (TPR), will decide to assess the evidential weight attached to any standard or guidance admitted.
Version
16. This is version 1.1 of the draft technical standards. Refer to the changelog for updates since the last publication.
Back to topTechnical overview
Client registration
17. Registration of OAuth clients (pension providers and schemes and pension dashboard providers) is required for the operation of the user-managed access (UMA) profiles. The governance register (which includes the UMA authorization server as the software entity managing software client registration) will provide services for client registration.
18. Static client registration is being used.
Overview of the pensions dashboards ecosystem participants
19. The following diagram shows each participant involved in the protocol interactions detailed in this document.
Pensions dashboards ecosystem participants
20. The participants in the ecosystem are:
- pension dashboard providers (MoneyHelper and commercial dashboards)
- central digital architecture (this encompasses the consent and authorization service, the pension finder service, the identity service and the governance register)
- pension providers, pension schemes, integrated service providers (ISPs), State Pension service
OpenAPI and JSON schema specifications
21. This version of the technical standards includes, and should be read in conjunction with the OpenAPI specifications contained in the “PDP_Technical_Standards_APIs_And_Schemas v1.1.zip”, and, with the json schemas detailing the find_request_token_payload and view_data_token_payload that are issued as part of the data standards. You can find these in the downloads section.
Back to topGUID creation protocols
22. All GUIDs used within the ecosystem are 32 hex digits (128 bits) allocated ‘randomly’ by standard methods and must be profiled using the approach in rfc4122 (https://www.ietf.org/rfc/rfc4122.txt).
Back to topIdentifiers
23. This section defines specific identifiers that must be understood by users of the ecosystem.
find_correlation_id
24. A correlation identifier provided in find-requests. This allows pension providers and schemes to identify where repeated find-requests are issued in relation to the same citizen user. Its format is a 256-bit hash value, represented as a 64-digit hexadecimal number.
holdernameGuid
25. holdernameGuids are identifiers provided by the pension provider or scheme. They are associated with one or more parts of regulated pension providers or schemes.
assetGuid
26. An assetGuid is a globally unique identifier (GUID) allocated by the pension provider or scheme in relation to a pension asset, on the pension provider or scheme systems, and find_correlation_id.
Pension identifier (PeI)
27. Within the ecosystem, the PeI is a unique resource location identifier for a pension asset that has been registered with the CDA. It is composed of two GUIDs separated by a colon, <holdernameGuid>:<assetGuid>.
28. They are generated by pension providers or schemes (or their ISPs) and must be globally unique. HoldernameGUIDs are registered by pension providers or schemes during the connection process. The holdernameGuid is registered against a view_data_host_url which identifies a base url and endpoint to be used when attempting to retrieve data using the view-data API. More than one holdernameGuid can be registered with the same view_data_host_url.
29. Operational retention period: pension providers and schemes are required by the legislation to create pension identifiers in accordance with PDP technical standards for a positive match. The legislation also sets out requirements in respect of de-registration where a match is made by the member ceases to be a relevant member. A pension identifier is therefore a long-lived identifier which persists and remains registered with the consent and authorization service for as long as the pension asset to which it relates belongs to a 'relevant member' of a pension scheme in scope of the dashboards service as defined in legislation. The pension provider or scheme that registered the pension identifier has obligations under the dashboards legislation to de-register the pension identifier where the member ceases to be a relevant member. Where a possible match is registered but the user either does not make contact within 30 days to resolve the match, or where the user does make contact, but the provider or scheme is unable to resolve the possible match.
30. The persistence of the pension identifier at the consent and authorization service, however, is subject to the user's account at the consent and authorization service remaining active. If the user's account is deleted as a result of a period [TBC] of non-use, or by the active decision of the user to delete their account, the pension identifiers will then expire.
holdernameViewDataUrl
31. The view_data_host_url is the base URL to be used when accessing view-data. It is associated with one or more holdernameGuids.
Back to topConnection (onboarding) information
32. Participants will work through a number of processes to connect to the PDP ecosystem. These processes are defined outside of the technical standards, but this section provides a summary of the technical information which will need to be supplied by participants to PDP, or by PDP by participants, to enable participants to interface with the PDP ecosystem. This information is also intended to support the API definitions and sequence diagrams defined in the later sections of the technical standards.
Provided by PDP
token_host_url
token_host_url
Format: URL.
Description: The host for the token resource endpoint. For example: https://[CDA URL]/ig/token. Also known as the as_uri.
Scope: One per shared environment.
rreguri_host_url
rreguri_host_url
Format: URL.
Description: The host for the rreguri resource registration endpoint For example: https://[CDA URL]/ig/rreguri.
Scope: One per shared environment.
introspect_host_url
introspect_host_url
Format: URL.
Description: The host for the introspect resource endpoint. For example: https://[CDA URL]/ig/introspect.
Scope: One per shared environment.
perm_host_url
perm_host_url
Format: URL.
Description: The host for the permission endpoint. For example: https://[CDA URL]/ig/perm.
Scope: One per shared environment.
authorize_host_url
authorize_host_url
Format: URL.
Description: The host for the authorization endpoint. For example: https://[CDA URL]/ig/authorize.
Scope: One per shared environment.
jwks_host_url
jwks_host_url
Format: URL.
Description: The host for the jwks endpoint. For example: https://[CDA URL]/ig/jwk_uri.
Scope: One per shared environment.
JWT_audience
JWT_audience
Format: String.
Description: Authentication server. AS identifier to be supplied/provided in JWTs where the AS is the audience for the token.
Scope: One per shared environment.
Crypto material: certificate package
Crypto material: certificate package
Format: Package (zip).
Description: Contains the participant certificate, certificate chain and the private and public keys to be used to secure the mTLS connection between parties.
Scope: One per shared environment.
Crypto material: signing key package
Crypto material: signing key package
Format: Package (zip).
Description: Contains the private and public keys and the key identifier (kid), to be used to sign and verify the signature of JWTs.
Scope: One per shared environment.
Provided by each pension provider or scheme
find_request_path_url
find_request_path_url
Format: URL.
Description: The path to the service that the pension provider or scheme provides to implement the find-requests API. For example: https://api.mypensionservice/dashboards/find.
Scope: One per shared environment.
view_data_host_url
view_data_host_url
Format: URL.
Description: The host for the view_data resource endpoint. For example: https://api.mypensionservice/dashboards/view-data1/view-data.
Scope: One per shared environment. A view_data_host_url may be registered against multiple holdernameGuids.
holdernameGuid
holdernameGuid
Format: Hex string.
Description: The holdernameGuid is the identifier for the pension provider or scheme from which pension details are returned to users at dashboards.
Scope: One per shared environment.
Tokens
Token summary
33. The PDP ecosystem is built on user managed access (UMA 2.0) and thus utilises the tokens required/permitted by UMA 2.0:
- Requesting party access token: RPT
- Permissions ticket: PMT
- Protection API token: PAT
- Persisted claims token: PCT
The PDP UMA 2.0 profile adds a custom claims token:
- Requesting party: RQP
34. In addition, the PDP technical standards also define the following tokens:
- user token
- user account token
- view data token
35. The information for each token is summarised in the below, with further details provided in the subsequent sections.
RQP
RQP
Issuer: Dashboard.
Signed: Yes.
Encrypted: No.
Time to live: 60 seconds and one time use.
Purpose: Asserts the user at the dashboard.
PMT
PMT
Issuer: CDA.
Signed: No.
Encrypted: Yes.
Time to live: 60 seconds and one time use.
Purpose: Used to request an RPT.
RPT
RPT
Issuer: CDA.
Signed: No.
Encrypted: Yes.
Time to live: 5 days.
Purpose: Authorizes the dashboard to retrieve PeIs from the CDA and pensions view data from pension providers or schemes. Each RPT relates to a single UMA resource.
PCT
PCT
Issuer: CDA.
Signed: No.
Encrypted: Yes.
Time to live: 90 days.
Purpose: Represents the association of the identity of the requesting party (user) at dashboard and at the Authorization Server. Used to ‘refresh’ RPTs.
PAT
PAT
Issuer: CDA.
Signed: Yes.
Encrypted: No.
Time to live: TBC.
Purpose: Authorizes pension providers and schemes to create/update/delete PeIs, introspect RPTs and obtain PMTs.
user_token
user_token
Issuer: CDA.
Signed: Yes.
Encrypted: No.
Time to live: 60 seconds and one time use.
Purpose: Encapsulates the verified and self-asserted “find” data of an individual citizen.
user_account_token
user_account_token
Issuer: CDA.
Signed: Yes.
Encrypted: No.
Time to live: 60 seconds.
Purpose: Authorizes pension providers and schemes to request a PAT.
view_data_token
view_data_token
Issuer: Pension provider or scheme.
Signed: Yes.
Encrypted: No.
Time to live: 60 seconds.
Purpose: Encapsulates the pension “view” data returned by a pension provider or scheme for a pension asset.
General token principles
- unless stated otherwise, all tokens are JSON Web Tokens (JWT) as per RFC7519
- JWTs contain base64 encoded JSON
- all tokens are signed using RS256
- certain tokens are encrypted as summarised in the table above and detailed in the individual token sections below
- where the token receiver (dashboard or pension provider or scheme) is only required to “store and forward” and not process the token contents, then on receipt of the token:
- the token does not need to be decrypted (if applicable)
- the token does not need to be decoded
- the token signature does not need to be validated (if applicable)
- the token schema does not need to be validated
- where the token receiver (dashboard or pension provider or scheme) is required to process the token contents, then on receipt of the token:
- the token must be decoded
- the token signature must be validated
- the token schema must be validated
- token validity periods (IAT, EXP and NBF where present) must be respected
Where applicable, this behaviour is specified and detailed in the individual token sections below.
JSON web token (JWT) signing and verification
36. As part of the process to onboard to the CDA the participant will receive a crypto package. This will contain the signing key material. Included is the private key which must be used to generate the signature. This uses RS256 as the signing algorithm to sign a JWT.
37. To verify the signature of a JWT the CDA will expose a centralised JWKS endpoint. The participant must be able to call this endpoint to retrieve a jwk for the kid provided in the JWT header. This can be converted to a pem which can then be used to verify the signature.
38. Participants must ensure they pass their assigned “kid” parameter. This will be part of the JWT header when returning pension details back to a dashboard. The “kid” will be generated as part of connection and its format will be a GUID. Participants will receive this as part of the crypto package.
Example of JWT header containing “kid” parameter
{
"alg": "RS256",
"typ": "JWT",
"kid": "ec1abf89-225b-49c2-ab87-1d425ac70f8d"
}
Requesting party (RQP)
- PDP UMA profile name: pension_dashboard_rqp
Purpose
39. The RQP (Requesting Party) represents the pensions dashboard’s assertion at the time of authorization. It confirms of the identity of the user, the dashboard instance and the user’s role. The PDP CDA uses the RQP to link the user@dashboard to the CDA user record.
Description
40. For the schema see “rqp v1_1.json”. The RQP token is a JWT defined as per the referenced schema, containing the following claims.
- REQUIRED iss: Unique identifier within dashboard ecosystem of the dashboard instance issuing the JWT. Provided to the dashboard provider during connection (onboarding).
- REQUIRED sub: Unique identifier within scope of iss, of the requesting party (user) which is authenticated to iss at the time the JWT is issued. Format [uniqueUserId]@[iss].
- REQUIRED aud: Unique identifier within the scope of the dashboard ecosystem of the Authorization Server. Provided to the dashboard provider during connection (onboarding).
- REQUIRED iat: Time of issue.
- REQUIRED exp: Time of expiry.
- REQUIRED jti: Unique token identifier.
- REQUIRED role: States the role in which the requesting party is acting. String value. Must be set to “owner”.
Usage
41. The client (dashboard) must issue an RQP aligning with the supplied schema. This must contain claims to identify the user, the dashboard instance, and the role the user is playing in using the dashboard. It must be presented with every authorization request. It must also assert that the user acting in a role is controlling the dashboard instance. The RQP token does not need to be bound to the client (Authorization Server).
- for each authorization attempt the issuer is required to mint a new RQP token
- the token must be signed by the issuer (dashboard) using the private key supplied by PDP as part of Connection (onboarding)
Permissions ticket (PMT)
- PDP UMA profile name: pension_dashboard_pmt
Purpose
42. The permissions ticket (PMT) is a correlation handle representing requested permissions. The Authorization Server creates and maintains the PMT. It enables the client to request an RPT.
Description
43. The PMT token is a JWT as defined in the PDP UMA profile. However, as these tokens are issued and consumed by the Authorization Server, they should be treated as opaque by other parties. These other parties would include dashboard clients and pension providers or schemes. Consequently, no schema is provided.
Usage
44. The PMT is generated by the PDP CDA (Authorization Server). It can be passed to different destinations based on how it was generated. It is either passed to the dashboard client directly by the CDA, or to the dashboard by the pension provider or scheme (Resource Server).
45. The PMT must be presented by the dashboard client, at the token endpoint and during requesting party redirects. Permission tickets have very short lifetimes. They are single use and they are protected from replay.
- the token will be encrypted by the issuer (Authorization Server)
- the client receiver (dashboard) does not need to decrypt the token
- PMTs are single use; the Authorization Server will issue a new token with a new JTI for every iteration of the permission process
- the client (dashboard) must discard any existing RPT for the resources owned by the pension owner (to which the permission ticket relates), whether a new RPT is issued or not
Requesting party access token (RPT)
- PDP UMA profile name: pension_dashboard_rpt
Purpose
46. The requesting party access token (RPT) contains the details of an authorization request. It will detail the specific requesting party (pension owner), and also the specific dashboard client. This will allow access to specific resources at a Resource Server (pension provider or scheme) with stated scope.
Description
47. The RPT token is a JWT as defined in the PDP UMA profile. However, as these tokens are issued and consumed by the Authorization Server, they should be treated as opaque by other parties. These other parties would include dashboard clients and pension provider or schemes. Consequently no schema is provided.
Usage
48. The RPT is generated by the PDP CDA (Authorization Server). It is returned to the dashboard as a result of the successful processing of a PMT.
49. RPT is used by the dashboard as the authorization token for requests to access UMA protected resources. The UMA protected resources could be PeIs hosted by the CDA provided via the “Retrieve PeI” flow. They could also be pensions asset information hosted by pension providers or schemes, provided via the “Get View Data Request” flow. Separate RPTs are required for retrieving PeIs and for each accessed pensions asset.
50. After receiving a request containing an RPT, pension providers and schemes must introspect the RPT against the CDA Introspect API. The pension provider or scheme uses the PAT to authorize the introspect API interaction.
- the token will be encrypted by the issuer (Authorization Server)
- the client receiver (dashboard, pension provider or scheme) does not need to decrypt the token
- the token may be persisted by the dashboard in accordance with policy (if the client is capable of suitably protecting the token). The token should be deleted by the dashboard if or when the dashboard makes an unsuccessful attempt to access a resource using it (indicating the token has exceeded its lifetime or has been revoked)
- the dashboard client should provide its existing RPT for the resource it requested in the previous call to the same resource server for the same requesting party, if it has one.
- The RPT is bound via OMTLS to the dashboard client by the Authorization Server when it is issued
- the Authorization Server may revoke a token for its own reasons at any time (including resource owner revocation of policy)
- the token should be presented to the resource server (pension provider or scheme) by the dashboard, the token must be introspected by the resource server at the Authorization Server introspection endpoint, the results of introspection must not be cached at the resource server
- introspection of the RPT is used to:
- validate the OAuth MTLS Token Binding fingerprint (of the client, by the Authorization Server)
- support revocation of the RPT at any time
- resource servers are responsible for access to the resource. The introspection response needs to be compared with what is stored internally for the resource to ensure access request is authorized.
Persisted claims token (PCT)
- PDP UMA profile name: pension_dashboard_pct
Purpose
51. The persisted claims token (PCT) represents the association of the identity of the requesting party (user). The PCT is represented at the dashboard and at the Authorization Server, where it retains the assured user state. This allows the PCT to serve as an ‘enhanced’ refresh token over longer timeframes.
52. The use of the PCT removes the need for the user to step up their authentication level for every authorization request. It does this by creating a persistent association between the user and role at the dashboard instance with their identity at the Authorization Server assured to (a higher) standard.
Description
53. The PCT is a JWT as defined in the PDP UMA profile. However, these tokens are issued and consumed by the Authorization Server. Therefore, they should be treated as opaque by other parties such as the dashboard clients. Consequently, no schema is provided.
Usage
54. The PCT is issued from, and presented at, the Authorization Server token end point. This is part of an authorization request and/or response by the dashboard.
55. The PCT supports the user experience of being able to silently re-authorize across all the user's resource servers. This would be based on their assured identity for a defined period (the PCT Time to live).
- the token will be encrypted by the issuer (Authorization Server)
- the client receiver (dashboard) does not need to decrypt the token
- the PCT is bound via OMTLS to the dashboard client by the Authorization Server when it is issued
56. The token may be persisted by the dashboard to support future authorization requests. This would apply in the case of the same requesting party in the same role. The client must be capable of suitably protecting the token.
57. The dashboard must delete the PCT when it is presented with a new PCT by the Authorization Server, for the same user, in the same role. Or should delete the PCT if or when the dashboard makes an unsuccessful attempt to access a resource using it. This would indicate the token has exceeded its lifetime or has been revoked.
58. The token must be presented to the token endpoint at the Authorization Server by the dashboard client.
Protection API token (PAT)
- PDP UMA profile name: pension_dashboard_pat
Purpose
59. The protection API token (PAT) allows Resource Servers to register UMA protected resources. This would be on behalf of the resource owner, a pensions owner. Note in this case Resource Servers are pension providers or schemes. UMA protected resources are pension assets.
60. The PAT is also used to authorize Resource Servers. This allows them to introspect RPTs received with pensions data view requests.
61. It can also be used to retrieve PMTs from the CDA. This would be useful where the RPT in the pensions data view request is missing or expired.
Description
62. The PAT is a JWT as defined in the PDP UMA profile. However, these tokens are issued and consumed by the Authorization Server. Thus, they should be treated as opaque by other parties such as the pensions providers or schemes. Consequently, no schema is provided.
Usage
63. Pension owners grant permission for the Authorization Server to determine their access policy. This controls access to pension owner's protected resources. This would be at one or more Resource Servers holding pension assets managed by pension providers. Pension owners are able to do this in their role as resource owners.
64. The PAT is an OAuth token of scope uma_protection.
65. PATs must be persisted by the Resource Server to which they were issued. They must be associated with the resource owner’s record(s) at that location.
- the token will be signed by the issuer (Authorization Server)
- the client receiver (pension provider or scheme) does not need to validate the signature
- the PAT is bound to the Resource Server client when it is issued
- the Authorization Server may revoke a PAT for its own reasons at any time (including resource owner revocation of policy)
66. The token may be deleted by the Resource Server if it is revoked or when the Resource Server makes an unsuccessful attempt to access an Authorization Server API using it.
User token
Purpose
67. The user token encapsulates the verified and self-asserted personal data for an individual user performing a request to find their pensions.
Description
68. For the schema see find_request_token_payload json (issued as part of the data standards).
69. The user token is a JWT as defined in the referenced schema, issued by the PDP CDA. Pension providers and schemes are required to parse and process the user token contents. This would be as part of processing the find request.
Usage
70. A user token is included with every find request sent by the PDP CDA to pension providers or schemes:
- the token will be signed by the issuer (PDP CDA)
- the client (pension provider or scheme) must validate the signature of the token
- the client must validate the token contents against the published version of the token schema
- the token and its contents must not be persisted by the pension provider or scheme. They must not persist beyond the time period required to process the find request and register any matching pensions assets
User account token
Purpose
71. The user account token enables a Resource Server (pension provider or scheme) to obtain a PAT on behalf of the resource owner. It is a temporary credential.
Description
72. The user account token is a JWT. These tokens are issued and consumed by the Authorization Server. Thus they should be treated as opaque by other parties such as the dashboard clients. Consequently, no schema is provided.
Usage
73. The user account token is an OAuth2 authorization grant. This is expressed as a JWT, which can be exchanged for the PAT. It is provided alongside the user token with every find request sent by the PDP CDA to pension providers or schemes.
74. The pension provider or scheme is required to use the user account token to request a PAT. This is following a successful find operation where it needs to register one or more found pensions assets with the PDP CDA.
- the token will be signed by the issuer (PDP CDA)
- the client receiver does not need to validate the signature
- the token must not be persisted by the pension provider or scheme. They must not be stored beyond the time period required to process the find request and a PAT
View data token
Purpose
75. The view data token encapsulates the data related to the matched pension asset. It includes associated retirement illustrations. This is returned with the pensions view data request.
Description
For the schema see view_data_token_payload json (issued as part of the data standards).
76. The view data token is returned by a pension provider or scheme to a dashboard in response to a view pensions data request. It is a JWT as defined in the referenced schema. Pension providers and schemes are required to structure the view data token to align with the schema. Dashboards are also required to parse and process the view data token contents to ensure alignment with the schema.
Usage
77. A view data token is returned in the view pensions data response. This is sent from a pension provider or scheme to the requesting dashboard.
- the token will be signed by the issuer (pension provider or scheme)
- the client (dashboard) must validate the signature of the token
- the issuer and client must ensure the token structure and contents align with the published version of the token schema
- the token and its contents must not be persisted by the dashboard beyond the user session at the dashboard
API technical standards
Transaction monitoring
78. Transaction monitoring and correlation will be achieved in the following way:
- all interfaces will carry a unique transaction identifier GUID (X-Request-ID) for logging, audit and monitoring purposes
- the transaction identifier must also be unique between retried requests
- the transaction identifier is issued by the party which starts the transaction. Both parties to the transaction must retain the same transaction identifier in their respective audit logs
- for transactions which PDP initiates, PDP will generate the identifier; for transactions which the pension provider, scheme or QPDS initiates, it must generate the identifier
- for API calls the transaction ID must be transmitted via the HTTP header: X-Request-ID.
- when redirecting to the consent and authorization service, dashboard providers must include the transaction identifier (request_id) in the URL as a query parameter. For example https://{url}?request_id={request_id}
Caching
79. Pension providers and schemes must not cache API responses.
Third-party standards
80. These standards are built upon a number of third-party standards:
UMA grant 2.0
UMA grant 2.0
- Issuing authority: Kantara Initiative
- Contact details: https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html
- Version: 2.0
UMA federated authorization 2.0
UMA federated authorization 2.0
- Issuing authority: Kantara Initiative
- Contact details: https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-federated-authz-2.0.html
- Version: 2.0
API definitions
Authorization
81. In general permission to access API endpoints is governed by mTLS. This is possible because the PDP ecosystem is a closed ecosystem. Within the ecosystem participants are registered and endpoints are secured using private PKI certificates issued on registration. This allows connections to be established via a mutual TLS connection with the central infrastructure. It also allows connections between dashboards providers and pension providers and schemes using the same mechanism.
82. Additional authorization may be required for specific endpoints. This is detailed in the documentation for specific APIs.
Encoding
83. Request and response bodies must be UTF-8 encoded.
Definitions
find-requests (find) API
find-requests (find) API
The find-requests API is hosted by pension providers and schemes. The purpose of the find-request API is to accept and act upon find requests issued by the CDA.
These requests contain the pension owner’s PII data. This data must be used by each pension provider or scheme to determine matches against their internal records.
In addition to the PII data, the find request will also provide a user_account_token, user account token. This user_account_token is used to retrieve a PAT (protection API token), PAT. The PAT is required by the pension providers and schemes to register and maintain PeI resources.
Hosted by: Pension providers or schemes.
Called by: CDA.
Used in:
- pension provider or scheme:match pensions and register PeIs
OpenAPI specification: See “find-requests v1_2.yaml” and the find_request_token_payload (issued as part of the data standards).
Performance and SLA’s : See code of connection (CoCo2.1.1, CoCo2.1.2, CoCo2.1.4, CoCo2.1.5)
token API
token API
The token API is hosted by the CDA. It is used by pension providers and schemes and dashboard providers to obtain access tokens in the form of JWTs. The access token JWTs are used throughout the system to allow access to controlled resources.
The token endpoint is an implementation of the standard access token endpoint. This is described at https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.
Hosted by: CDA.
Called by: Pension providers or schemes or pensions dashboard providers.
Used in:
- pension provider or scheme: match pensions and register PeIs
OpenAPI specification: See “token v1_2.yaml”.
rreguri API
rreguri API
The rreguri API is hosted by the CDA. Pension providers and schemes use this API to register and maintain registered PeIs relating to pensions matched as a result of find-requests. The permitted states and transition paths are documented in the pensions identifier (PeI) status and transition section.
Once a PeI has been registered, responsibility for maintaining the PeI belongs with the pension providers or schemes. This responsibility remains with pension providers and schemes until they have deleted the registered PeI.
Hosted by: CDA.
Called by: Pension providers or schemes.
Used in:
- pension provider or scheme:match pensions and register PeIs
- pension provider or scheme:update match status
- pension provider or scheme:delete registered PeI
OpenAPI specification: See “rreguri v1_2.yaml”.
Authorization: In addition to the standard use of mTLS, a valid PAT must be sent as bearer authentication with each request.
view-data API
view-data API
The view-data API is hosted by pension providers or schemes. It is called by dashboard providers to retrieve pension and pension illustration details. These details will be associated with a pension asset that has been registered under a PeI.
Hosted by: Pension providers or schemes.
Called by: Pensions dashboard providers.
Used in:
- pension provider or scheme:get view data request
OpenAPI specification: See “view-data v1_1.yaml” and the view_data_token_payload schema (issued as part of the data standards).
Authorization: In addition to the standard use of mTLS, a valid RPT must be sent as bearer authentication for the GET request.
Performance and SLA’s: See code of connection (CoCo2.1.3, CoCo2.1.4, CoCo2.1.5).
introspect API
introspect API
The introspect API is hosted by the CDA. It is used by pension providers and schemes to check whether access tokens provided in requests provide sufficient permissions to allow access to requested data. Specifically, the pension providers and schemes will check if an RPT provided in a view-data request grants sufficient access for the view data to be returned.
Hosted by: CDA.
Called by: Pension providers or schemes.
Used in:
- pension provider or scheme:get view data request
OpenAPI specification: See “introspect v1_1.yaml”.
Authorization: In addition to the standard use of mTLS, a valid PAT must be sent as Bearer authentication for the GET request.
perm API
perm API
The perm (permissions) API is hosted by the CDA. It is used by pension providers and schemes to retrieve permission tokens. These permission tokens are returned to view-data API clients so that they can obtain the correct access token (RPT) to retrieve data that they have requested.
Hosted by: CDA.
Called by: Pension providers or schemes.
Used in:
- pension provider or scheme:get view data request
OpenAPI specification: See “perm v1_1.yaml”.
Authorization: In addition to the standard use of mTLS, a valid PAT must be sent as bearer authentication for the GET Request.
Sequences diagrams and API usage
Pension provider or scheme – match pensions and register PeIs
Scenario
84. This section details the interactions that occur between the ecosystem participants in the scenario where a find request is issued by the CDA.
85. The find request must be immediately acknowledged by the pension provider or scheme, which will then enact a search based on the match criteria provided for the citizen user in the request and the pension asset owner details held on the pension provider or scheme systems.
86. For each match identified, the pension provider or scheme will register an appropriate PeI with the CDA.
Ecosystem participants
- CDA
- pension provider or scheme
APIs
- find-requests: Hosted by pension provider or scheme.
- token: Hosted by CDA.
- rreguri: Hosted by CDA.
API usage details
87. The sections below describe the detailed usage of the APIs in this scenario.
CDA issues find request
88. The CDA issues a request for the pension provider or scheme to initiate a search for pensions matching based on criteria provided in the User Token.
89. A pension provider or scheme will use the information provided in the user token to determine if there any matches within the internal records of pension asset owners.
Call Data Provider POST find-requests Request
Name | Sent as | Source | Logic |
---|---|---|---|
BaseUrl&Endpoint | Not applicable. | Provided by the pension provider or scheme during onboarding. | See find_request_host_url. |
X-Request-ID | Header. | Generated by CDA. | A unique ID for the request to allow tracing of request flows. |
find_correlation_id | Header. | Generated by CDA. | A unique identifier to link find-requests that are issued in relation to a particular citizen user. |
user_token | Request body. | Generated by CDA. | See user token. The user token payload must be validated against the expected schema. |
user_account_token | Request body. | Generated by CDA. | See user account token. This is a JWT token which Data Provider does not need to interpret but will use to obtain a PAT, see PAT. The pension provider or scheme should not attempt to validate the token. The user account token will expire 60 seconds after issue. This aligns with the SLA for registering a PeI after a find request has been issued. |
Call Data Provider POST find_requests Response (202 Success)
Name | Sent as | Source | Logic |
---|---|---|---|
Not applicable. | Provided by the pension provider or scheme. | Not applicable. | The pension provider or scheme must immediately respond to the request with an acknowledgement of the request. |
Call Data Provider POST find_requests Response (400 Bad Request)
Name | Sent as | Source | Logic |
---|---|---|---|
Not applicable. | Provided by the pension provider or scheme. | Not applicable. | Pension provider or scheme must immediately respond to invalid requests. This may include if the request has invalid, or missing, parameters or the user token is not correctly signed or its payload does not conform to the schema. The pension provider or scheme must immediately respond to the request with the 400, Bad Request, response. |
Pension provider or scheme obtains PAT
90. The pension provider or scheme will identify any full or possible matches between the citizen user details provided in the find request and the pension asset owner details on their systems. Any possible or full matches identified must be registered with the CDA, see repeated match behaviour for special behaviour in repeat match scenarios.
91. Before registering matching assets, the pension provider or scheme will need to obtain a PAT. A single PAT should be used to register all the pension assets for a particular pension asset owner/citizen user. If, when a new match is identified, pension asset owner already has a PAT associated with them. This existing PAT should be used to register the new pension asset rather than retrieving a new PAT.
92. The User Account Token provided in the find request is an OAuth2 authorization grant. This is expressed as a JWT (JSON web token) which can be exchanged for the PAT as described below. This is an OAuth2 access token, as per the OAuth2 standard.
Call CDA POST token Request
Name | Sent as | Source | Logic |
---|---|---|---|
BaseUrl&Endpoint | Not applicable. | Provided to the pension provider or scheme in the onboarding pack during the Connection process. | See token_host_url. |
grant_type | Query parameter. | Provided by the pension provider or scheme. | In this scenario the pension provider or scheme will set this to "urn:ietf:params:oauth:grant-type:jwt-bearer". |
assertion | Query parameter. | Provided by the CDA. | The user account token provided in the find_requests call. |
scope | Query parameter. | Provided by the pension provider or scheme. | In this scenario the pension provider or scheme will set to "uma_protection". |
Call CDA POST token Response (200 Success)
Name | Sent as | Source | Logic |
---|---|---|---|
access_token | Response body. | Provided by the CDA. | The owner PAT expressed as a JWT. The Data Provider does not need to interpret the token but will use it when accessing the rreguri API endpoints. |
token_type | Response body. | Provided by the CDA. | The pension data provider must check that this is “pension_dashboard_pat”. The data provider should throw an exception if the value is not correct. |
Pension provider or scheme registers PeI(s)
93. Once the pension provider or scheme has obtained a PAT they must register any identified matches with the CDA.
94. The pension provider or scheme will record sufficient information about a successful registration to allow the pension provider or scheme to maintain the registered PeIs and to service calls to retrieve the view-data associated with the associated assetGuid.
95. In order to enable this the recorded information will need to include the following:
- assetGuid: A unique identifier for a pension asset owner/ find_correlation_id. Where there are multiple matches against a pension asset owner for find-requests with different find_correlation_ids the pension provider or scheme must generate a unique ID for each so that they can identify which match is associated with a particular view-data request, see pension provider or scheme – get view data request.
- resource_id: The ID for the registered PeI resource provided in the success response returned when the PeI resource is registered.
- PAT: The current PAT that can be user to maintain the registered PeI and introspect RPTs in relation to view-data requests (initially this will be the PAT used to register the PeI).
- match-status: The current status of the match.
- find_correlation_id: As passed in the find request, this is required to resolve repeated match scenarios, see repeated match behaviour.
96. It may also need to include these attributes to link to the internal date held by the pension provider or scheme:
- pensionOwnerIdentifier (the internal ID for a pension owner): The pension provider or scheme internal identifier for a pension asset owner.
- internalAssetIdentifier (the internal ID for a pension asset): The pension provider or scheme internal identifier for a pension asset.
Call CDA POST rreguri Request
Name | Sent as | Source | Logic |
---|---|---|---|
BaseUrl&Endpoint | Not applicable. | Provided to the pension provider or scheme in the onboarding pack during the connection process. | See rreguri_host_url. |
X-Request-ID | Header. | Generated by the pension provider or scheme. | A unique ID for the request to facilitate tracing. |
Authorization: | Header. | Provided by the CDA. | The access_token provided in the Post tokens response. Provided as "Bearer " + access_token. |
resource_scopes | Request body. | Provided by the pension provider or scheme. | In this scenario the pension provider or scheme will set the scopes to [“value”, “owner”, “delegate”]. |
name | Request body. | Provided by the pension provider or scheme. | The urn for the PeI to be registered in the form "urn:pei:<PeI>. |
type | Request body. | Not applicable. | Not currently used, for future functionality. |
description | Request body. | Provided by the pension provider or scheme. | This must be the "scheme name" that will be returned in response to the GET pension-details (view) response for the PeI. |
match-status | Request body. | Determined by the data provider. | The initial match status for the registered PeI. Either "match-yes" for a full match or "match-possible" for a possible match. |
inbound_request_id | Not applicable. | Not applicable. | In this instance the X-Request-ID sent in the find request. |
Call CDA POST rreguri Response (201 Success)
Name | Sent as | Source | Logic |
---|---|---|---|
Location | Header. | Provided by the pension provider or scheme. | The location of the resource. For example, https://cdapath/registered-peis/resource_id. |
resource_id | Response body. | Provided by the pension provider or scheme. | The unique_id of the newly created registered-peis. |
Pension provider or scheme – update match status
Scenario
97. This section details the interactions between the ecosystem participants when pension provider or scheme processes determine that that the match status needs of a registered PeI needs to be updated. This could be because:
- A possible match has been resolved to a full match either due to a manual process or a repeated match scenario, see behaviour where there is a pre-existing current match.
Ecosystem participants
- CDA
- pension provider or schemes
APIs
- rreguri: Hosted by CDA.
Sequence diagram
API usage details
98. The section below describes the detailed usage of the APIs in this scenario.
Call CDA PATCH rreguri Request
Name | Sent as | Source | Logic |
---|---|---|---|
BaseUrl&Endpoint | Base URL | Provided to the pension provider or scheme in the onboarding pack during the connection process. | See rreguri_host_url. |
X-Request-ID | Header. | Generated by pension provider or scheme. | A unique ID for the request to facilitate tracing. |
Authorization: | Header. | The access_token (PAT) provided in the Post token response received during the PeI registration process, access_token. | "Bearer " + access_token. The PAT token held against the pei in relation to the pension owner whose match status has been clarified. |
resource_id | Path parameter. | Returned from by the CDA in the POST rreguri response. | Not applicable. |
match-status | Request body. | Determined by the data provider. | The new match status, this may only be "match-yes". |
inbound_request_id | Request body. | Not applicable. | If the status change was triggered by a request made received from the CDA. For example, a repeated find-request, the X-Request-ID sent in the find-request. If the update was not triggered by the CDA this should not be provided. |
Call CDA Patch rreguri Response (200 Success)
Name | Sent as | Source | Logic |
---|---|---|---|
resource_id | Response body. | Not applicable. | The unique_id of the updated rreguri. |
Pension provider or scheme – delete registered PeI
Scenario
99. This section details the interactions between the ecosystem participants when the pension provider or scheme determines that registered PeI needs to be deleted. This may be triggered in the following scenarios:
- a possible match is determined to not be a match
- a possible match was not confirmed as full within 30 days of being registered
- the pension provider or scheme identifies that a PeI was registered erroneously
- registered PeI relates to a crystalised or transferred pension asset
Ecosystem participants
- CDA
- pension provider or schemes
APIs
- rreguri: Hosted by CDA.
Sequence diagram
API usage details
100. The section below describes the detailed usage of the APIs in this scenario.
Call CDA DELETE rreguri Request
Name | Sent as | Source | Logic |
---|---|---|---|
BaseUrl&Endpoint | Base URL. | Provided to the pension provider or scheme in the onboarding pack during the connection process. | See rreguri_host_url. |
X-Request-ID | Header. | Generated by the pension provider or scheme. | A unique ID for the request to facilitate tracing. |
deletion_reason | Header. | Determined by the pension provider or scheme. | The reason that the PeI resource is being deleted: match-no – a match-possible has previously been registered but found not to be a match; match-timeout – a possible match has previously been registered but has since been removed (for example, if the pension owner did not confirm a match within the required time period); match-withdrawn – an erroneous match was yes but has now been withdrawn; asset-removed – a previously registered PeI has been removed (for example, benefit crystalised or transferred out). |
Authorization: | Header. | The access_token provided in the Post token response, access_token. | "Bearer " + access_token |
resource_id | Path parameter. | The resource ID return in the POST rreguri response, resource_id. | Not applicable. |
CDA DELETE rreguri Request Response (204 Success)
Name | Sent as | Source | Logic |
---|---|---|---|
Not applicable. | Not applicable. | Not applicable. | Not applicable. |
Pension provider or scheme – get view data request
Scenario
101. This section details the interactions between the ecosystem participants in the scenario where a pension dashboard provider requests the pension details related to a particular assetGuid from a pension provider or scheme.
Ecosystem participants
- pension dashboard providers
- pension providers or schemes
APIs
- view-data: Hosted by pension provider or scheme.
- introspect: Hosted by CDA.
- perm: Hosted by CDA.
Sequence diagram