Dynamic Client Registration (DCR)
- Version 3.2.1
- Protocol: HTTPS
- Sandbox well-known endpoint: see Channel and market specific API documentation
- Production well-known endpoint: see Channel and market specific API documentation
Introduction
This API provides access to the Dynamic Client Registration API
- Register a client by way of a Software Statement Assertion
- Get a client by way of Client ID
- Update a client by way of Client ID
Version
Change log and release history:
|
Version |
Sandbox Status |
Production Status |
|---|---|---|
|
V3.2.1 |
Live |
Live |
Feedback and Support
Dive in and start coding your applications. If you get stuck or require additional support, please contact our team using the Contact Us form found under the Help menu.
Dynamic Client Registration (DCR)
Third Party Registration
The Open Banking Read/Write API standard is relying on FAPI Read-Write specification as means for authenticating TPPs (Third Party Providers) and PSUs (Payment Service Users). In order to enable this capability the TPP must register their OAuth API Clients with HSBC's Open Banking Platform. The HSBC Open Banking Platform supports v3.2 of Dynamic Client Registration Protocol [RFC 7591] in line with OBIE specifications.
Production Access
TPPs have to register with their National Competent Authority (NCA) and obtain appropriate TLS and Signing certificates based on jurisdiction.
They are also expected to sign up and setup an entity on Open Banking Directory platform. Once a Software Statement is being created in Open Banking Directory, the TPP can register the API client on HSBC Open Banking platform using DCR endpoint.
Brand Specific Variations
TPPs need to check the address of HSBC's Open Banking registration endpoint using our well-known endpoints:
DCR Endpoints
The following API endpoints for Dynamic Client Registration are supported.
| Endpoint | Description |
|---|---|
| POST /register | Register new client |
| GET /register/{client-id} | Get details of already registered API client |
Register new client
The client registration endpoint is designed to allow a API client to be registered with HSBC's Open Banking authorization server.
Please note the following related to DCR v3.2:
- The `Content-Type` request header should be set to `application/jose`.
- The JWT claim 'aud' should be set to same value as the ‘issuer’ from well-known configuration endpoint.
- The JWT claim 'exp' should be set to a maximum of 30 min.
Here is an example of a CURL command for client registration endpoint in Sandbox:
@POST/register_curl
Notice, the request body represents a Compact Serialization of the JSON Web Signature (JWS) [RFC 7515]. Decoding above JWS will result in the following:
@POST/register_curl_decoded_jwt
Where:
- The `iss` is a claim parameter defined by [RFC 7519].
- The `aud` is a claim parameter defined by [RFC 7519]. Must be set to `issuer` value from the well-known configuration endpoint.
- The `scope` is a set of space-separated list of scope values that the client can use when requesting access tokens. For supported scopes see `scopes_supported` in the well-known configuration endpoint. For a detailed set of combined scopes see Scope Value section on this page.
- The `redirect_uris` is the list of callback URLs supported by TPP's server. Typically this is where the bank customer (resource owner) is going to be redirected back to TPP's realm after consenting or rejecting the 'allow access request' to owner's resource using `GET /authorize` endpoint (OpenID Connect Core) [RFC 6749].
- The `response_types` should always be set to `code id_token`.
- The `grant_types` is the grant types that the client can use at the token endpoint.
- The `application_type` is a free string that represents the type of TPP's application.
- The `id_token_signed_response_alg` is the signing algorithm to be used by authorization server when signing `id_token` value. Supported value is `PS256`.
- The `request_object_signing_alg` is the signing algorithm used by TPP when signing the request parameter passed in `GET /authorize` request. Supported value is `PS256`.
- The `token_endpoint_auth_method` is the client authentication method to be used at token endpoint. See Client Authentication section for supported values.
- The `token_endpoint_auth_signing_alg` is to instruct the token endpoint which signing algorithm to use in order to check client assertion signature. Supported value is `PS256`. This claim is used in conjuction with `token_endpoint_auth_method` when it's value is set to `private_key_jwt`.
- The `software_statement` is the Software Statement as defined by [RFC 7591]. For supported claims see Software Statement section defined on this page.
- The `software_id` is the id of the registered client. This claim must have same value as `software_id` from the Software Statement.
- The `exp` is a claim parameter defined by [RFC 7519].
- The `iat` is a claim parameter defined by [RFC 7519].
- The `jti` is a claim parameter defined by [RFC 7519].
Here is an example of client registration response:
@POST/uk_register_curl_response
Get client details
This endpoint can be used only to request registration details for an existing client id. The `Authorization` header should be used and contain Bearer token issued with grant type `client_credentials`..
Here is a CURL example how to retrieve existing API Client details:
@GET/uk_client_detail_curl
Update client details
This endpoint can be used to update details for an existing client id. The `Authorization` header should be used and contain Bearer token issued with grant type `client_credentials`. Relevant checks will be performed to ensure the updates are valid/allowed. An error message will be returned in case of failure.
The request body should be same as response received from the `GET /register` request as a Signed JWT.
It is important to note that any value that does not need an update is still expected to be sent in the request.
Here is a CURL example how to update existing API client details:
@PUT/uk_client_detail_curl
Software Statement
The [RFC 7591] defines a Software Statement as a digitally signed or MACed JSON Web Token (JWT) [RFC7519] that asserts metadata values about the client software. In some cases, a software statement will be issued directly by the client developer. In other cases, a software statement will be issued by a third-party organization for use by the client developer. In both cases, the trust relationship the authorization server has with the issuer of the software statement is intended to be used as an input to the evaluation of whether the registration request is accepted. A software statement can be presented to an authorization server as part of a client registration request.
Currently, HSBC's Open Banking authorization server is supporting software statements issued by OBIE Directory. A complete list of supported Software Statement Assertion (SSA) fields is provided below:
|
Metadata |
Description |
Mandatory |
|---|---|---|
|
software_id |
Unique Identifier for TPP Client Software [RFC7591]. ^[0-9a-zA-Z]{1,22}$ |
Yes |
|
iss |
SSA Issuer [RFC7519], acting as TPP identifier. This value must be unique for each TPP registered by the issuer of the SSA. ^[0-9a-zA-Z]{1,22}$ |
Yes |
|
iat |
The timestamp when the SSA was issued [RFC7519]. |
Yes |
|
jti |
JWT ID [RFC7519]. Max 36 characters, typically a v4 UUID. |
Yes |
|
software_client_id |
Registered API client ID which is used to authenticate the client at token endpoint. Base62 GUID (22 chars). HSBC Implementation supports max 36 chars. |
Yes |
|
software_client_description |
Human-readable detailed description of the API client. Max 256 characters. |
No |
|
software_client_name |
Human-readable name of the client software. Max 40 characters. See also TPP agent name display section. |
No |
|
software_client_uri |
The website or resource root URI. Typically it's where TPPs would describe in more details their client software or their business. Max 256 characters. |
No |
|
software_version |
The version number of the software if TPP is going to support multiple versions for maintainance purpose. Example: `1.0` |
No |
|
software_environment |
The environment where the software is allowed to be used. Max 256 characters. |
No |
|
software_jwks_endpoint |
Contains all active public keys for the software statement. Typically Authorization Servers use it to validate the signature of the software statement. Max 256 characters. |
Yes |
|
software_jwks_revoked_endpoint |
Contains all revoked public keys for the software statement. Max 256 characters. |
No |
|
software_logo_uri |
Link to the TPP logo. Note, ASPSPs are not obliged to display images hosted by third parties. Max 256 characters. |
No |
|
software_mode |
Field to indicate that this software is `Test` or `Live` (default is `Live`). Impact and support for `Test` software is up to the ASPSP. |
No |
|
software_on_behalf_of_org |
A reference to the 4th party organisation on the Open Banking Directory if the registering TPP is acting on behalf of another. Max 40 characters. See also TPP agent name display section. |
No |
|
software_policy_uri |
A link to the software policy page. Max 256 characters. |
No |
|
software_redirect_uris |
A list of client callback endpoints. Typically for `authorization_code` flow this is where the TPP will receive the authorisation code (aka `code` parameter) in case of successful authorisation to the requested consent. Array of strings, each max 256 characters. (?:\\[([0-9a-fA-F:]+)\\]|(?:(?:[a-zA-Z0-9%-._~!$&'()*+,;=]+(?::[a-zA-Z0-9%-._~!$&'()*+,;=]*)?@)?([\\p{Alnum}\\-\\.]*)))(?::(\\d*))?(.*)? |
Yes |
|
software_roles |
A multi value list of roles that this software is authorized to perform. AISP | PISP | CBPII |
Yes |
|
software_tos_uri |
A link to the software terms of service page. Max 256 characters. |
No |
|
organisation_competent_authority_claims |
Authorizations granted to TPP organisation by the NCA. |
Yes |
|
org_status |
Included to cater for voluntary withdrawal from Open Banking scenarios. Active | Revoked | Withdrawn |
Yes |
|
org_id |
Unique organisation ID of the TPP. HSBC Implementation supports max 18 chars. |
Yes |
|
org_name |
Legal Entity Identifier or other known Organisation Name. Max 140 characters. See also TPP agent name display section. |
No |
|
org_contacts |
JSON array of objects containing a triplet of `name`, `email`, `phone`. Max 256 characters. |
No |
|
org_jwks_endpoint |
Contains all active public keys of the TPP organisation. Typically used to validate the signature of the request (query parameters, headers, body) by Authorization or Resource Servers. Max 256 characters. |
No |
|
org_jwks_revoked_endpoint |
Contains all revoked public keys of the TPP organisation. Max 256 characters. |
No |
|
typ |
Must be set to `JWT`. |
Yes |
|
alg |
Must be set to `PS256`. |
Yes |
|
kid |
The key identifier will be kept same as the `x5t` parameter (X.509 Certificate SHA-1 Thumbprint) of the signing certificate. |
Yes |
Here is an example of a Software Statement issued by HSBC's Open Banking Sandbox (decoded JWT Header and Payload):
@sandbox_sofware_statement
The Software Statement is validated by HSBC's Open Banking authorization server during TPP's registration request for an API client.
Where do TPPs get the Software Statement from:
| Target Environment | Source |
|---|---|
| Production | Open Banking Directory |
| Sandbox | DevHub during project creation flow |
TPP agent name display
Please note that TPPs must ensure that they have registered using the appropriate fields so that the correct information is displayed to customers during consent authorization step.
| Options | Display | Display Rule | Client Name | Org Name | On Behalf Of Org | Display Result |
|---|---|---|---|---|---|---|
| When org_name & software_client_name are available & both are same & software_on_behalf_of_org not available | All (single name and key point) | Use software_client_name as TPP name | ABC Company Ltd | ABC Company Ltd | N/A | ABC Company Ltd |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org not available | All (single name and key point) | Use software_client_name as TPP name | ABC Trades | ABC Company Ltd | N/A | ABC Trades |
| When org_name & software_client_name are available & both are same & software_on_behalf_of_org is available & is same as well | All (single name and key point) | Use software_client_name as TPP name | ABC Company Ltd | ABC Company Ltd | ABC Company Ltd | ABC Company Ltd |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org is available & is same as the org_name | Both names to be displayed (1) |
<Agent> on behalf of <TPP>
Where <Agent> is software_on_behalf_of_org and <TPP> is software_client_name.
|
ABC Trades | ABC Company Ltd | ABC Company Ltd | ABC Company Ltd on behalf of ABC Trades |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org is available & is same as the software_client_name | All (single name and key point) | Use software_client_name as TPP name | ABC Trades | ABC Company Ltd | ABC Trades | ABC Trades |
| When org_name & software_client_name are available & both are same & software_on_behalf_of_org is available & is different from both | Both names to be displayed (1) |
<Agent> on behalf of <TPP>
Where <Agent> is software_on_behalf_of_org and <TPP> is software_client_name.
|
ABC Company Ltd | ABC Company Ltd | OBO Ltd | OBO Ltd on behalf of ABC Company Ltd |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org is available & is different from both | Both names to be displayed (1) |
<Agent> on behalf of <TPP>
Where <Agent> is software_on_behalf_of_org and <TPP> is software_client_name.
|
ABC Trades | ABC Company Ltd | OBO Ltd | OBO Ltd on behalf of ABC Trades |
(1) Both names will always be displayed at the consent set-up step, however, for simplicity, single name may be displayed in some non-key steps within the journey.
Scope Value
The value of the `scope` claim in the registration request does specify what access privileges can be requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access HSBC's Open Banking protected endpoints.
|
Endpoint |
Journey |
Scopes |
Notes |
|---|---|---|---|
|
POST /register |
PIS |
"scope": "openid payments" |
A Journey needs to be chosen based on TPP specialization |
|
AIS |
"scope": "openid accounts" |
||
|
CoF |
"scope": "openid fundsconfirmations" |
||
|
PIS, AIS, CoF |
"scope": "openid payments accounts fundsconfirmations" |
Client Authentication
This section defines the client authentication methods supported by HSBC's Open Banking authorization server during DCR. The following values are supported for `token_endpoint_auth_method` claim:
- private_key_jwt [https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication]
- tls_client_auth [RFC 8705]
private_key_jwt
If `private_key_jwt` is used then claim `token_endpoint_auth_signing_alg` is also required.
tls_client_auth
If `tls_client_auth` is used then claim `tls_client_auth_subject_dn` is also required.
The value of `tls_client_auth_subject_dn` must be set to full DN (Distinguished Name) of the transport certificate that the TPP will present to the token endpoint to establish a mutual TLS connection between the client and authorization server. The order of DN attributes must be the same as in the certificate subject value. Please note that this should not include the word ‘Subject’, but only the DN value of the ‘Subject’ object field.
The expected format of `tls_client_auth_subject_dn` follows a string representation of the DN as defined in [RFC4514]. Please refer to [https://tools.ietf.org/html/rfc4512#section-2] for formal definition of DN, RDN and attribute value assertion (AVA).
Here is an example of a valid DN value:
CN=00158000016i44JAAQ,2.5.4.97=#131050534447422D4643412D373635313132,O=HSBC UK Bank Plc,C=GB
Supported short names for attribute types (https://tools.ietf.org/html/rfc4514#section-2) are:
| CN (2.5.4.3) |
| C (2.5.4.6) |
| L (2.5.4.7) |
| S (2.5.4.8) |
| ST (2.5.4.8) |
| O (2.5.4.10) |
| OU (2.5.4.11) |
| T (2.5.4.12) |
| IP (1.3.6.1.4.1.42.2.11.2.1) |
| STREET (2.5.4.9) |
| DC (0.9.2342.19200300.100.1.25) |
| DNQUALIFIER (2.5.4.46) |
| DNQ (2.5.4.46) |
| SURNAME (2.5.4.4) |
| GIVENNAME (2.5.4.42) |
| INITIALS (2.5.4.43) |
| GENERATION (2.5.4.44) |
| EMAIL (1.2.840.113549.1.9.1) |
| EMAILADDRESS (1.2.840.113549.1.9.1) |
| UID (0.9.2342.19200300.100.1.1) |
| SERIALNUMBER (2.5.4.5) |
Multiple keywords are available for one OBJECT IDENTIFIER (OID). Attribute types not present on above list should be encoded as the dotted-decimal encoding, a “numericoid”, of its OBJECT IDENTIFIER. The “numericoid” is defined in [RFC4512].
Example: 1.3.6.1.4.1.311.60.2.1.3=PL
Full Example: CN=[value],serialNumber=[value],OU=[value],O=[value],C=[value],ST=[value],2.5.4.97=[value],2.5.4.15=[value],1.3.6.1.4.1.311.60.2.1.3=[value]
Where [value] is a placeholder for any real value.
Digital Signatures
QSEALs or OBSEALS will also be required by TPPs to enable a digital signature feature. Use of a digital signature to sign payloads is mandatory.
Dynamic Client Registration (DCR)
Third Party Registration
The Open Banking Read/Write API standard is relying on FAPI Read-Write specification as means for authenticating TPPs (Third Party Providers) and PSUs (Payment Service Users). In order to enable this capability the TPP must register their OAuth API Clients with HSBC's Open Banking Platform. The HSBC Open Banking Platform supports v3.2 of Dynamic Client Registration Protocol [RFC 7591] in line with OBIE specifications.
Production Access
For APIs in Hong Kong to request access to Production APIs, Third Parties need to submit a request using the Help, Contact Us form in the portal.
- Select 'Open Banking APIs - HK - HSBC Business' or 'Open Banking APIs - HK - HSBC Personal' from the dropdown menu 'Which API does your query relate to?'
- Select 'Production Access' from the dropdown menu 'What does your query relate to?'
On receipt of this information the HSBC support team will review the Third Parties request and begin the process to on-board the Third Party to the Open Banking eco-system. The Software Statement Assertion (SSA) will be securely mailed to the Third Parties registered email address.
Brand Specific Variations
TPPs need to check the address of HSBC's Open Banking registration endpoint using our well-known endpoints:
DCR Endpoints
The following API endpoints for Dynamic Client Registration are supported.
| Endpoint | Description |
|---|---|
| POST /register | Register new client |
| GET /register/{client-id} | Get details of already registered API client |
Register new client
The client registration endpoint is designed to allow a API client to be registered with HSBC's Open Banking authorization server.
Please note the following related to DCR v3.2:
- The `Content-Type` request header should be set to `application/jose`.
- The JWT claim 'aud' should be set to same value as the ‘issuer’ from well-known configuration endpoint.
- The JWT claim 'exp' should be set to a maximum of 30 min.
Here is an example of a CURL command for client registration endpoint in Sandbox:
@POST/register_curl
Notice, the request body represents a Compact Serialization of the JSON Web Signature (JWS) [RFC 7515]. Decoding above JWS will result in the following:
@POST/register_curl_decoded_jwt
Where:
- The `iss` is a claim parameter defined by [RFC 7519].
- The `aud` is a claim parameter defined by [RFC 7519]. Must be set to `issuer` value from the well-known configuration endpoint.
- The `scope` is a set of space-separated list of scope values that the client can use when requesting access tokens. For supported scopes see `scopes_supported` in the well-known configuration endpoint. For a detailed set of combined scopes see Scope Value section on this page.
- The `redirect_uris` is the list of callback URLs supported by TPP's server. Typically this is where the bank customer (resource owner) is going to be redirected back to TPP's realm after consenting or rejecting the 'allow access request' to owner's resource using `GET /authorize` endpoint (OpenID Connect Core) [RFC 6749].
- The `response_types` should always be set to `code id_token`.
- The `grant_types` is the grant types that the client can use at the token endpoint.
- The `application_type` is a free string that represents the type of TPP's application.
- The `id_token_signed_response_alg` is the signing algorithm to be used by authorization server when signing `id_token` value. Supported value is `PS256`.
- The `request_object_signing_alg` is the signing algorithm used by TPP when signing the request parameter passed in `GET /authorize` request. Supported value is `PS256`.
- The `token_endpoint_auth_method` is the client authentication method to be used at token endpoint. See Client Authentication section for supported values.
- The `token_endpoint_auth_signing_alg` is to instruct the token endpoint which signing algorithm to use in order to check client assertion signature. Supported value is `PS256`. This claim is used in conjuction with `token_endpoint_auth_method` when it's value is set to `private_key_jwt`.
- The `software_statement` is the Software Statement as defined by [RFC 7591]. For supported claims see Software Statement section defined on this page.
- The `software_id` is the id of the registered client. This claim must have same value as `software_id` from the Software Statement.
- The `exp` is a claim parameter defined by [RFC 7519].
- The `iat` is a claim parameter defined by [RFC 7519].
- The `jti` is a claim parameter defined by [RFC 7519].
Here is an example of client registration response:
@POST/hk_register_curl_response
Get client details
This endpoint can be used only to request registration details for an existing client id. The `Authorization` header should be used and contain Bearer token issued with grant type `client_credentials`..
Here is a CURL example how to retrieve existing API Client details:
@GET/hk_client_detail_curl
Update client details
This endpoint can be used to update details for an existing client id. The `Authorization` header should be used and contain Bearer token issued with grant type `client_credentials`. Relevant checks will be performed to ensure the updates are valid/allowed. An error message will be returned in case of failure.
The request body should be same as response received from the `GET /register` request as a Signed JWT.
It is important to note that any value that does not need an update is still expected to be sent in the request.
Here is a CURL example how to update existing API client details:
@PUT/hk_client_detail_curl
Software Statement
The [RFC 7591] defines a Software Statement as a digitally signed or MACed JSON Web Token (JWT) [RFC7519] that asserts metadata values about the client software. In some cases, a software statement will be issued directly by the client developer. In other cases, a software statement will be issued by a third-party organization for use by the client developer. In both cases, the trust relationship the authorization server has with the issuer of the software statement is intended to be used as an input to the evaluation of whether the registration request is accepted. A software statement can be presented to an authorization server as part of a client registration request.
Currently, HSBC's Open Banking authorization server is supporting software statements issued by OBIE Directory. A complete list of supported Software Statement Assertion (SSA) fields is provided below:
|
Metadata |
Description |
Mandatory |
|---|---|---|
|
software_id |
Unique Identifier for TPP Client Software [RFC7591]. ^[0-9a-zA-Z]{1,22}$ |
Yes |
|
iss |
SSA Issuer [RFC7519], acting as TPP identifier. This value must be unique for each TPP registered by the issuer of the SSA. ^[0-9a-zA-Z]{1,22}$ |
Yes |
|
iat |
The timestamp when the SSA was issued [RFC7519]. |
Yes |
|
jti |
JWT ID [RFC7519]. Max 36 characters, typically a v4 UUID. |
Yes |
|
software_client_id |
Registered API client ID which is used to authenticate the client at token endpoint. Base62 GUID (22 chars). HSBC Implementation supports max 36 chars. |
Yes |
|
software_client_description |
Human-readable detailed description of the API client. Max 256 characters. |
No |
|
software_client_name |
Human-readable name of the client software. Max 40 characters. See also TPP agent name display section. |
No |
|
software_client_uri |
The website or resource root URI. Typically it's where TPPs would describe in more details their client software or their business. Max 256 characters. |
No |
|
software_version |
The version number of the software if TPP is going to support multiple versions for maintainance purpose. Example: `1.0` |
No |
|
software_environment |
The environment where the software is allowed to be used. Max 256 characters. |
No |
|
software_jwks_endpoint |
Contains all active public keys for the software statement. Typically Authorization Servers use it to validate the signature of the software statement. Max 256 characters. |
Yes |
|
software_jwks_revoked_endpoint |
Contains all revoked public keys for the software statement. Max 256 characters. |
No |
|
software_logo_uri |
Link to the TPP logo. Note, ASPSPs are not obliged to display images hosted by third parties. Max 256 characters. |
No |
|
software_mode |
Field to indicate that this software is `Test` or `Live` (default is `Live`). Impact and support for `Test` software is up to the ASPSP. |
No |
|
software_on_behalf_of_org |
A reference to the 4th party organisation on the Open Banking Directory if the registering TPP is acting on behalf of another. Max 40 characters. See also TPP agent name display section. |
No |
|
software_policy_uri |
A link to the software policy page. Max 256 characters. |
No |
|
software_redirect_uris |
A list of client callback endpoints. Typically for `authorization_code` flow this is where the TPP will receive the authorisation code (aka `code` parameter) in case of successful authorisation to the requested consent. Array of strings, each max 256 characters. (?:\\[([0-9a-fA-F:]+)\\]|(?:(?:[a-zA-Z0-9%-._~!$&'()*+,;=]+(?::[a-zA-Z0-9%-._~!$&'()*+,;=]*)?@)?([\\p{Alnum}\\-\\.]*)))(?::(\\d*))?(.*)? |
Yes |
|
software_roles |
A multi value list of roles that this software is authorized to perform. AISP | PISP | CBPII |
Yes |
|
software_tos_uri |
A link to the software terms of service page. Max 256 characters. |
No |
|
organisation_competent_authority_claims |
Authorizations granted to TPP organisation by the NCA. |
Yes |
|
org_status |
Included to cater for voluntary withdrawal from Open Banking scenarios. Active | Revoked | Withdrawn |
Yes |
|
org_id |
Unique organisation ID of the TPP. HSBC Implementation supports max 18 chars. |
Yes |
|
org_name |
Legal Entity Identifier or other known Organisation Name. Max 140 characters. See also TPP agent name display section. |
No |
|
org_contacts |
JSON array of objects containing a triplet of `name`, `email`, `phone`. Max 256 characters. |
No |
|
org_jwks_endpoint |
Contains all active public keys of the TPP organisation. Typically used to validate the signature of the request (query parameters, headers, body) by Authorization or Resource Servers. Max 256 characters. |
No |
|
org_jwks_revoked_endpoint |
Contains all revoked public keys of the TPP organisation. Max 256 characters. |
No |
|
typ |
Must be set to `JWT`. |
Yes |
|
alg |
Must be set to `PS256`. |
Yes |
|
kid |
The key identifier will be kept same as the `x5t` parameter (X.509 Certificate SHA-1 Thumbprint) of the signing certificate. |
Yes |
Here is an example of a Software Statement issued by HSBC's Open Banking Sandbox (decoded JWT Header and Payload):
@sandbox_sofware_statement
The Software Statement is validated by HSBC's Open Banking authorization server during TPP's registration request for an API client.
Where do TPPs get the Software Statement from:
| Target Environment | Source |
|---|---|
| Production | Open Banking Directory |
| Sandbox | DevHub during project creation flow |
TSP agent name display
Please note that TPPs must ensure that they have registered using the appropriate fields so that the correct information is displayed to customers during consent authorization step.
| Options | Display | Display Rule | Client Name | Org Name | On Behalf Of Org | Display Result |
|---|---|---|---|---|---|---|
| When org_name & software_client_name are available & both are same & software_on_behalf_of_org not available | All (single name and key point) | Use software_client_name as TPP name | ABC Company Ltd | ABC Company Ltd | N/A | ABC Company Ltd |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org not available | All (single name and key point) | Use software_client_name as TPP name | ABC Trades | ABC Company Ltd | N/A | ABC Trades |
| When org_name & software_client_name are available & both are same & software_on_behalf_of_org is available & is same as well | All (single name and key point) | Use software_client_name as TPP name | ABC Company Ltd | ABC Company Ltd | ABC Company Ltd | ABC Company Ltd |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org is available & is same as the org_name | Both names to be displayed (1) |
<Agent> on behalf of <TPP>
Where <Agent> is software_on_behalf_of_org and <TPP> is software_client_name.
|
ABC Trades | ABC Company Ltd | ABC Company Ltd | ABC Company Ltd on behalf of ABC Trades |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org is available & is same as the software_client_name | All (single name and key point) | Use software_client_name as TPP name | ABC Trades | ABC Company Ltd | ABC Trades | ABC Trades |
| When org_name & software_client_name are available & both are same & software_on_behalf_of_org is available & is different from both | Both names to be displayed (1) |
<Agent> on behalf of <TPP>
Where <Agent> is software_on_behalf_of_org and <TPP> is software_client_name.
|
ABC Company Ltd | ABC Company Ltd | OBO Ltd | OBO Ltd on behalf of ABC Company Ltd |
| When org_name & software_client_name are available & both are different & software_on_behalf_of_org is available & is different from both | Both names to be displayed (1) |
<Agent> on behalf of <TPP>
Where <Agent> is software_on_behalf_of_org and <TPP> is software_client_name.
|
ABC Trades | ABC Company Ltd | OBO Ltd | OBO Ltd on behalf of ABC Trades |
(1) Both names will always be displayed at the consent set-up step, however, for simplicity, single name may be displayed in some non-key steps within the journey.
Scope Value
The value of the `scope` claim in the registration request does specify what access privileges can be requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access HSBC's Open Banking protected endpoints.
|
Endpoint |
Journey |
Scopes |
Notes |
|---|---|---|---|
|
POST /register |
AIS |
"scope": "openid accounts" |
Client Authentication
This section defines the client authentication methods supported by HSBC's Open Banking authorization server during DCR. The following values are supported for `token_endpoint_auth_method` claim:
- private_key_jwt [https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication]
private_key_jwt
If `private_key_jwt` is used then claim `token_endpoint_auth_signing_alg` is also required.