Introduction
The Version Delta tab can be used to see in context changes between this version of the standards and the immediately previous version of the standards.
This text is an example of a new addition to the standards:
+ New text added here
This text is an example of text removed from the standards:
- Old text removed
Note: changes to request and response payloads are listed at the beginning of the relevant API section due to the documentation being auto generated from OpenAPI specification files.
These standards have been developed as part of the Australian Government's introduction of the Consumer Data Right legislation to give Australians greater control over their data.
The Consumer Data Right (CDR) is intended to be applied sector by sector across the whole economy, beginning in the banking, energy and telecommunications sectors. These standards have been developed to facilitate the Consumer Data Right by acting as a specific baseline for implementation.
These standards are maintained by the Data Standards Body (DSB) within Treasury, with the Data Standards Chair as the independent decision maker. The work of standards development is conducted in consultation with the Australian Competition and Consumer Commission (ACCC) and Office of the Australian Information Commissioner) (OAIC) as co-regulators of the Consumer Data Right (CDR).
The standards are required to be published. The obligations on CDR participants to apply the published standards commence on the commencement of the Consumer Data Right rules:
- where the rules require compliance with the standards, non-compliance with the standards may constitute a breach of the rules.
- where the standards are specified as binding standards as required by the Consumer Data Right rules for the purposes of s56FA of the legislation, they apply as under contract between a data holder and an accredited data recipient. The legal effect of binding standards as between data holders and accredited data recipients is fully set out in s56FD and s56FE of the legislation.
Some of these standards will be binding data standards under the Competition and Consumer (Consumer Data Right) Data Standards (No. 1) 2023. See that instrument here. In summary, provisions of these standards (as they exist from time to time) that impose obligations or prohibitions on CDR entities are binding data standards. Provisions included in these standards merely by way of guidance are not binding data standards.
Version
These standards represent version 1.28.0 of the high level standards. See the versioning section for more information on how versions are managed in the standard.
Interpretation
Note that, in these standards, the key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in [RFC2119].
Future Dated Obligations
The standards, as published from time to time, may include specific statements indicating that a specific section of the standards will not take effect until a future date or may cease to have effect on some future date.
The table below highlights these areas of the standards.
Section | Description | Applicable Date |
---|---|---|
Get Account Detail V1 | Data holders MAY retire version 1 of this end point from February 28th 2023. Data recipients MUST upgrade their implementations to use version 2 by this time | February 28th 2023 |
Get Product Detail V3 | Data holders MAY retire version 3 of this end point from February 28th 2023. Data recipients MUST upgrade their implementations to use version 4 by this time | February 28th 2023 |
Get Customer Detail V1 | Data holders MAY retire version 1 of this end point from February 28th 2023. Data recipients MUST upgrade their implementations to use version 2 by this time | February 28th 2023 |
Get Energy Accounts V2 | Data Holders MUST implement v2 of this endpoint by April 14th 2023 | April 14th 2023 |
Get Energy Account Detail V2 |
|
April 14th 2023 |
Information Security profile | FAPI 1.0 adoption is introduced across four phases. Phase 3: Support Authorization Code Flow and Hybrid Flow includes, amongst other changes:
|
April 14th 2023 |
Error Codes: Secondary Data Holder flag |
|
May 15th 2023 |
Information Security profile | FAPI 1.0 adoption is introduced across four phases. Phase 4: Retire Hybrid Flow:
|
July 10th 2023 |
Get Accounts V2 | Version 2 of this end point MUST be made available by affected data holders by July 10th 2023 | July 10th 2023 |
Get Account Detail V3 | Version 3 of this end point MUST be made available by affected data holders by July 10th 2023 | July 10th 2023 |
Get Generic Plan Detail V2 |
|
November 1st 2023 |
Get Energy Account Detail V3 |
|
November 1st 2023 |
Get Billing For Account V2 |
|
November 1st 2023 |
Get Bulk Billing V2 |
|
November 1st 2023 |
Get Billing For Specific Accounts V2 |
|
November 1st 2023 |
Get Metrics V4 |
|
November 1st 2023 |
Private Key JWT Client Authentication | Change to support [RFC7521] such that, until November 13th 2023, clients authenticating using Private Key JWT are recommended to provide the client_id , but no longer required. From November 13th 2023, it is then optional to provide the client_id . This applies to ADRs and the CDR Register authenticating with Data Holders and ADRs authenticating with the CDR Register. |
November 13th 2023 |
Get Accounts V1 | Data Holders MAY decommission v1 of this end point from March 11th 2024 | March 11th 2024 |
Get Account Detail V2 | Data Holders MAY decommission v2 of this end point from March 11th 2024 | March 11th 2024 |
Get Scheduled Payments for Account V2 |
|
March 11th 2024 |
Get Scheduled Payments Bulk V2 |
|
March 11th 2024 |
Get Scheduled Payments For Specific Accounts V2 |
|
March 11th 2024 |
Get Metrics V3 |
|
May 13th 2024 |
Get Metrics v5 |
|
May 13th 2024 |
Register Implementation Schedule
The implementation of the Register APIs is managed by the ACCC.
Their implementation schedule is published here.
Endpoint Version Schedule
A table-view of all endpoint versioning is available here.
Normative References
Reference | Description | Version |
---|---|---|
[DCR] | OAuth 2.0 Dynamic Client Registration Protocol: https://datatracker.ietf.org/doc/html/rfc7591 | July 2015 |
[FAPI-1.0-Baseline] | Financial-grade API Security Profile 1.0 - Part 1: Baseline: https://openid.net/specs/openid-financial-api-part-1-1_0.html | March 2021 |
[FAPI-1.0-Advanced] | Financial-grade API Security Profile 1.0 - Part 2: Advanced: https://openid.net/specs/openid-financial-api-part-2-1_0.html | March 2021 |
[JARM] | Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM): https://bitbucket.org/openid/fapi/src/master/Financial_API_JWT_Secured_Authorization_Response_Mode.md | October 2020 |
[JSON] | The JavaScript Object Notation (JSON) Data Interchange Format: https://tools.ietf.org/html/rfc8259 | December 2017 |
[JWA] | JSON Web Algorithms (JWA): https://tools.ietf.org/html/rfc7518 | May 2015 |
[JWE] | JSON Web Encryption (JWE): https://tools.ietf.org/html/rfc7516 | May 2015 |
[JWK] / [JWKS] | JSON Web Key (JWK): https://tools.ietf.org/html/rfc7517 | May 2015 |
[JWS] | JSON Web Signature (JWS): https://tools.ietf.org/html/rfc7797 | February 2016 |
[JWT] | JSON Web Token (JWT): https://tools.ietf.org/html/rfc7519 | May 2015 |
[MTLS] | OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens: https://tools.ietf.org/html/rfc8705 | February 2020 |
[OAUTH2] | The OAuth 2.0 Authorization Framework: https://tools.ietf.org/html/rfc6749 | October 2012 |
[OIDC] | OpenID Connect Core 1.0 incorporating errata set 1: http://openid.net/specs/openid-connect-core-1_0.html | November 2014 |
[OIDD] | OpenID Connect Discovery 1.0 incorporating errata set 1: http://openid.net/specs/openid-connect-discovery-1_0.html | November 2014 |
[PAR] | OAuth 2.0 Pushed Authorization Requests RFC9126: https://tools.ietf.org/html/rfc9126 | September 2021 |
[PKCE] | Proof Key for Code Exchange by OAuth Public Clients: https://datatracker.ietf.org/doc/html/rfc7636 | September 2015 |
[TDIF] | Digital Transformation Agency - Trusted Digital Identity Framework https://www.digitalidentity.gov.au/tdif | April 2019 |
[RFC2119] | Key words for use in RFCs to Indicate Requirement Levels https://tools.ietf.org/html/rfc2119 | March 1997 |
[RFC2397] | The "data" URL scheme: https://tools.ietf.org/html/rfc2397 | August 1998 |
[RFC3339] | Date and Time on the Internet: Timestamps: https://tools.ietf.org/html/rfc3339 | July 2002 |
[RFC4122] | A Universally Unique IDentifier (UUID) URN Namespace: https://tools.ietf.org/html/rfc4122 | July 2005 |
[RFC4627] | The application/json Media Type for JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627 | October 2006 |
[RFC4648] | The Base16, Base32, and Base64 Data Encodings: https://tools.ietf.org/html/rfc4648 | October 2006 |
[RFC5322] | Internet Message Format: https://tools.ietf.org/html/rfc5322 | October 2008 |
[RFC6750] | The OAuth 2.0 Authorization Framework: Bearer Token Usage: https://tools.ietf.org/html/rfc6750 | October 2012 |
[RFC7009] | OAuth 2.0 Token Revocation: https://tools.ietf.org/html/rfc7009 | August 2013 |
[RFC7521] | Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants: https://tools.ietf.org/html/rfc7521 | May 2015 |
[RFC7523] | JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants: https://tools.ietf.org/html/rfc7523 | May 2015 |
[RFC7662] | OAuth 2.0 Token Introspection: https://tools.ietf.org/html/rfc7662 | October 2015 |
[RFC8414] | OAuth 2.0 Authorization Server Metadata: https://tools.ietf.org/html/rfc8414 | June 2018 |
[RFC9126] | OAuth 2.0 Pushed Authorization Requests: https://tools.ietf.org/html/rfc9126 | September 2021 |
Informative References
Reference | Description |
---|---|
[ACCC] | The Australian Competition and Consumer Commission is responsible for accrediting data recipients to participate in CDR, building and maintaining the Register of data recipients and data holders, providing support and guidance to participants and promoting compliance with the CDR rules and standards, including taking enforcement action where necessary. https://www.accc.gov.au/focus-areas/consumer-data-right-cdr-0 |
[ANZSCO] | ANZSCO - Australian and New Zealand Standard Classification of Occupations : http://www.abs.gov.au/ANZSCO |
[ANZSIC-2006] | 1292.0 - Australian and New Zealand Standard Industrial Classification (ANZSIC), 2006 (Revision 2.0) : http://www.abs.gov.au/anzsic |
[BCP195] | Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS): https://tools.ietf.org/html/bcp195 |
[CDR] | Consumer Data Right: https://www.cdr.gov.au |
[E.164] | The international public telecommunication numbering plan: http://www.itu.int/rec/T-REC-E.164-201011-I/en |
[FAPI] | Financial-Grade API - Home Page https://openid.net/wg/fapi/ |
[OAIC] | The Office of the Australian Information Commissioner is responsible for regulating privacy and confidentiality under the CDR. The OAIC also handles complaints and notifications of eligible data breaches relating to CDR data. https://www.oaic.gov.au/consumer-data-right |
[RFC3966] | The tel URI for Telephone Numbers: https://tools.ietf.org/html/rfc3966 |
[RFC7231] | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content: https://tools.ietf.org/html/rfc7231 |
[Treasury] | The Treasury leads CDR policy, including development of rules and advice to Government on which sectors the CDR should apply to in the future. The DSB within Treasury is responsible for the creation of the technical standards for the sharing of product and consumer data. https://treasury.gov.au/consumer-data-right |
[X.1254] | X.1254 - Entity authentication assurance framework: https://www.itu.int/rec/T-REC-X1254-201209-I/en |
High Level Standards
This section contains components of the standards that are foundational and generally applicable.
Principles
The following principles, classified as Outcome Principles and Technical Principles, are the basis for the development of the standards for the Consumer Data Right.
Outcome Principles
These principles articulate qualitative outcomes that the API definitions should seek to deliver.
Outcome Principle 1: APIs are secure
The API definitions will consider and incorporate the need for a high degree of security to protect customer data. This includes the risk of technical breach but also additional concerns of inadvertent data leakage through overly broad data payloads and scopes. The security of customer data is a first order outcome that the API standards must seek to deliver.
Outcome Principle 2: APIs use open standards
In order to promote widespread adoption, open standards that are robust and widely used in the industry will be used wherever possible.
Outcome Principle 3: Data sharing provides a positive consumer experience
The standards will ensure that CDR consumers have simple, informed, and trustworthy data sharing experiences that provide them with positive outcomes over the short and long term.
Outcome Principle 4: APIs provide a good developer experience
To ensure that the entry hurdle for new developers is low the experience of the developers that are building clients using the APIs will be considered. The ability for a developer to easily understand and write code using the APIs in modern development environments should be facilitated by the API standards.
Outcome Principle 5: Standards are consistent across sectors
The standards will strive for consistency in patterns, structure, security mechanisms and user experience across sectors to facilitate the development of customer experiences and services that are able to integrate data from multiple sectors seamlessly and to reduce the cost of customer education for new sectors.
Technical Principles
These principles articulate specific technical outcomes that the API definitions should seek to deliver.
Technical Principle 1: APIs are RESTful
The API standards will adhere to RESTful API concepts where possible and sensible to do so. In particular the concepts of statelessness and resource orientation will be followed.
Technical Principle 2: APIs are implementation agnostic
The underlying implementation of the APIs should not be constrained or driven by the API definitions and standards. Conversely, the underlying implementation choices should not be visible or derivable to the client applications using the APIs.
Technical Principle 3: APIs are simple
As complexity will increase implementation costs for both holders and clients as well as reduce the utility of the APIs, API definitions should seek to be as simple as possible but no simpler.
Technical Principle 4: APIs are rich in capability
As the APIs are defined care should be taken to ensure that the data payloads defined represent rich data sets that can be used in many scenarios, including scenarios not necessarily front of mind during the design process.
Technical Principle 5: APIs are performant
The API definitions should consider and incorporate performance implications during design ensuring that repeated calls are not necessary for simple use cases and that payload sizes do not introduce performance issues.
Technical Principle 6: APIs are consistent
The API definitions across the full suite of APIs should be consistent with each other as much as possible. Where possible common data structures and patterns should be defined and reused.
Technical Principle 7: APIs are version controlled and backwards compatible
As the API definitions evolve care will be taken to ensure the operation of existing clients are protected when breaking changes occur. Breaking changes will be protected by a well-defined version control model and by a policy of maintaining previous versions for a period of time to allow for backwards compatibility.
Technical Principle 8: APIs are extensible
The API definitions and standards should be built for extensibility. This extensibility should accommodate future API categories and industry sectors but it should also allow for extension by data holders to create unique, value add offerings to the ecosystem.
Consumer Experience Principles
These principles articulate qualitative outcomes for consumer experience that the standards should seek to deliver.
CX Principle 1: The CDR is Consumer-centric
The CDR consumer experience is intuitive and is centred on consumer attitudes, needs, behaviours, and expectations – noting that these may change over time.
CX Principle 2: The CDR is Accessible and Inclusive
A diverse range of people are able to access, use, and comprehend the CDR ecosystem regardless of their background, situation, experience, or personal characteristics.
CX Principle 3: The CDR is Comprehensible
When interacting with the CDR, consumers are able to understand the following:
- who their data is shared with;
- what information is shared;
- when sharing begins and ceases;
- where data is shared to and from;
- why their data is being requested; and
- how they can manage and control the sharing and use of their data.
CX Principle 4: The CDR is Simple and Empowering
Consumer interactions with the CDR are as simple as possible, but not at the expense of informed consent, consumer control, transparency, privacy, or comprehension. Consumers should be encouraged to be privacy conscious without experiencing cognitive loads that lead to disengagement. Consumers should also be empowered by the CDR without interactive burdens being placed on them.
CX Principle 5: Consent is Current
Consent is granted at a point in time and is only as current as the consumer’s original intent. Consumer attitudes and behaviours may change over time and be impacted by external events such as the expansion of the CDR or consumer awareness. Consent terms should always align to current consumer preferences.
Versioning
The standards have adopted a two level versioning strategy. The high level standards (including principles, Uniform Resource Identifier structure, payload naming conventions, etc) be versioned and each API end point will have an additional version specific to that end point.
Documentation Versioning
Sample versioning of the standards documentation is as follows:
1.12.2 - meaning major version 1, minor version 12 and bugfix version 2
The standards documentation will be versioned using three version parts <major>.<minor>.<bug fix>
. This version will be used to describe updates in the Change Log.
Each of the three components will be independently incrementing integers and are described as follows:
- major: Major version of the standards. Reserved for increment only when a set of changes are applied that are large enough to make co-existence in the same implementation environment with previous versions untenable. This would include major changes to the information security profile, major changes to the high level standards or a change in basic protocols.
- minor: Significant changes to the standards. This would include changes that require approval by the Chair of the Data Standards Body such as new end points and new versions of existing end points.
- bug fix: Minor documentation changes that clarify or correct the standards but do not meaningfully alter the standards.
Uniform Resource Identifier (URI) Versioning
The base path structure containing the "version" for this standard is:
https://<holder-path>/cds-au/v<major version>/<industry>
The high level standard will be versioned as described above. The major component of this version will be embedded in the URI Structure for the APIs. This allows for a data holder to support multiple major versions of the standards in production even if the significant breaking changes occur between major versions.
End Point Versioning
Each end point will have multiple versions independent of other end points. A specific end point version will be requested by a client using a HTTP header. This header will be supported by all end points under the API standards. See the section on HTTP Headers for more information on how versions are requested and supplied under the standards.
A table-view of all endpoint versioning is available here.
URI Structure
Some example URIs that meet this standard are:
1. https://www.bank.com.au/api/cds-au/v1/banking/accounts
2. https://www.bank.com.au/api/cds-au/v1/banking/accounts/abc123/transactions/?x=y#bar
3. https://www.bank.com.au/complex/uri/taxonomy/cds-au/v1/banking/products?page=2
4. https://www.energyretailer.com.au/api/cds-au/v1/energy/usage
5. https://www.energyretailer.com.au/api/cds-au/v1/ACME/apply
The holder path for each example is:
1. www.bank.com.au/api
2. www.bank.com.au/api
3. www.bank.com.au/complex/uri/taxonomy
4. www.energyretailer.com.au/api
5. www.energyretailer.com.au/api
The Base Path for each example is:
1. https://www.bank.com.au/api/cds-au/v1/banking
2. https://www.bank.com.au/api/cds-au/v1/banking
3. https://www.bank.com.au/complex/uri/taxonomy/cds-au/v1/banking
4. https://www.energyretailer.com.au/api/cds-au/v1/energy
5. https://www.energyretailer.com.au/api/cds-au/v1/ACME
The Resource Path for each example is:
1. https://www.bank.com.au/api/cds-au/v1/banking/accounts
2. https://www.bank.com.au/api/cds-au/v1/banking/accounts/abc123/transactions
3. https://www.bank.com.au/complex/uri/taxonomy/cds-au/v1/banking/products
4. https://www.energyretailer.com.au/api/cds-au/v1/energy/usage
5. https://www.energyretailer.com.au/api/cds-au/v1/ACME/apply
The URI structure for API end points in the standards MUST be implemented as follows:
uri-string = "https://" <holder-path> "/" cds-au "/" <version> "/" ( <industry> | <HID> ) "/" <resource>The components of this URI structure are described as follows:
- <holder-path> = string. The holder path is a path set by the data holder. It can be any URI desired by the holder. While all authenticated end points must be accessible under the same holder path the data holder may stipulate a different holder path for unauthenticated end points.
- cds-au = "cds-au" string. This is a static string representing the end points defined by the Consumer Data Standards for Australia. This static string allows for separation from other APIs available at the same base holder path and also allows for extension if the standards are adopted by another jurisdiction in whole or in part.
- <version> = "v1" string. The major version of the high level standards. This is not the version of the endpoint or the payload being requested but the version of the overall standards being applied. This version number will be “v” followed by the major version of the standards as a positive integer (e.g. v1, v12 or v76).
- <industry> = banking / energy / telco / common
A static string used to separate APIs for a specific industry. As standards for new industries are defined the list of industry strings will be extended.
Note that the currently accepted values for the
industry
component of the Base Path are:- banking = "banking" string. For APIs related to banking and potentially wider financial services data,
- energy = "energy" string. For APIs related to the energy distribution industry,
- telco = "telco" string. For APIs related to telecommunications,
- common = "common" string. For APIs that potentially span industries.
- <HID> = string. The Holder Identifier used to denote extension API categories for a specific holder.
- <resource> = string. The URI for the specific resource requested. This end point URI will be defined as part of the end point definitions for each API group.
Base Path
Base Path is intended to be the portion of the URL up to but not including the endpoint resource. In other words, the base path is the portion of the URL up to and including the <industry>
or <HID>
component. The Base Path string is defined as follows:
https:// <holder-path> / cds-au / <version> / ( <industry> | <HID> )
Resource Path
The Resource Path is intended to be the portion of the URL including the Base Path and resource location. The Resource Path string is defined as: <base-path> / <resource>
.
Resource URIs
Resources that are collections, and members of collections, will follow the JSONAPI.org recommendation.
Under this model, collections, individual members and collection sub-resources would be accessed as follows:
The final example above represents a complex query accessed via a POST request. In this situation the POST URI should be applied to a sub-resource of the collection. A POST to a collection is reserved for the creation of a new collection member.
If no valid sub-resource exists then a dedicated sub-resource should be created, such as the “search” URI listed in the example above.
HTTP Headers
Supported HTTP headers, and their usage, for the standards are as laid out in the following sections.
Request Headers
A sample set of headers requesting version 3 to 5:
Content-Type : application/json;charset=UTF-8
Accept : application/json;charset=UTF-8
x-v : 5
x-min-v : 3
x-fapi-interaction-id : 6ba7b814-9dad-11d1-80b4-00c04fd430c8
x-fapi-auth-date : Thu, 16 Jan 2020 16:50:15 GMT
x-fapi-customer-ip-address : 2001:0db8:85a3:0000:0000:8a2e:0370:7334
x-cds-client-headers : TW96aWxsYS81LjAgKFgxMTsgTGludXggeDg2XzY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvNzkuMC4zOTQ1Ljg4IFNhZmFyaS81MzcuMzY=
A Data Holder must be able to process Content-Type headers in accordance with [RFC7231]. The following would be valid:
Content-Type: application/json;charset=UTF-8
Content-Type: application/json
Content-Type: AppliCAtion/JSon;Charset=uTf-8
A Data Holder must be able to process Accept headers in accordance with [RFC7231]. The following would be valid:
Accept: */*
Accept: application/json;charset=UTF-8
Accept: application/json
Accept-Encoding: charset=UTF-8
Accept: AppliCAtion/JSon;Charset=uTf-8
Header Field | Description | Mandatory? |
---|---|---|
Content-Type | Standard HTTP Header. Represents the format of the payload provided in the request. The media type must be set to application/json . Mandatory for PUT and POST calls. |
Conditional |
Accept | If specified, the media type must be set to application/json , unless otherwise specified in the resource end point standard. If set to an unacceptable value the holder must respond with a 406 Not Acceptable. If not specified, or a wildcard (*/*) is provided, the default media type is application/json . |
Optional |
x-v | Version of the API end point requested by the client. Must be set to a positive integer. The holder should respond with the highest supported version between x-min-v and x-v . If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the holder must respond with a 406 Not Acceptable . |
Mandatory |
x-min-v | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The holder should respond with the highest supported version between x-min-v and x-v . If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the holder must respond with a 406 Not Acceptable . |
Optional |
x-<HID>-v | A holder specific version of extension fields. Should not be used in conjunction with x-min-v . |
Optional |
x-fapi-interaction-id | An optional [RFC4122] UUID used as a correlation id. If provided, the data holder must "play back" this value in the x-fapi-interaction-id response header. Not required for unauthenticated calls. |
Optional |
x-fapi-auth-date | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. | Conditional |
x-fapi-customer-ip-address | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. | Conditional |
x-cds-client-headers | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. This header is not required to include:
|
Conditional |
Response headers
Header Field | Description | Mandatory? |
---|---|---|
Content-Type | Standard HTTP Header. Represents the format of the payload returned in the response. Must be application/json unless otherwise specified in the resource end point standard. |
Mandatory |
Retry-After | Header indicating the time (in seconds) that the client should wait before retrying an operation. The holder should include this header along with responses with the HTTP status code of 429 Too many requests . |
Optional |
x-v | The version of the API end point that the holder has responded with. | Mandatory |
x-fapi-interaction-id | An [RFC4122] UUID used as a correlation id. The data holder must set the response header x-fapi-interaction-id to the value received from the corresponding request header or to a new [RFC4122] UUID value if the request header was not provided. This header MUST be responded for success and error responses for authenticated APIs. |
Mandatory |
Additional Headers
Generally understood headers used in HTTP transactions to provide caching guidance and the use of the compression are not specified but are considered acceptable. It is at the discretion of the data holder if these headers are used for a specific implementation. Data holders should not require these headers for successful API access, however.
HTTP Response Codes
The handling and usage of HTTP response codes for the standards will be according to the following table.
Situation | HTTP Status | Notes | POST | GET | DELETE |
---|---|---|---|---|---|
Query completed successfully | 200 OK | Yes | Yes | No | |
Normal execution. The request has succeeded. | 201 Created | The operation results in the creation of a new resource. | Yes | No | No |
Delete operation completed successfully | 204 No Content | No | No | Yes | |
The response is not modified since last call | 304 Not Modified | May be returned if standard caching headers such as ETag or If-modified-since are utilised | Yes | Yes | No |
Request has malformed, missing or non-compliant JSON body or URL parameters | 400 Bad Request | The requested operation will not be carried out. | Yes | Yes | Yes |
Authorization header missing or invalid token | 401 Unauthorized | The operation was refused access. Re-authenticating may result in an appropriate token that may be used. | Yes | Yes | Yes |
Token has incorrect scope or a security policy was violated. | 403 Forbidden | The operation was refused access. Re-authenticating is unlikely to remediate the situation. It is expected that this error will result in an error payload | Yes | Yes | Yes |
The resource matching the request URI is not known or is unable to be processed due to business logic specific to the resource being requested | 404 Not Found | No indication is given of whether the condition is temporary or permanent. This response code MUST NOT be used for resources presented in the body of the request. | Yes | Yes | Yes |
The consumer tried to access the resource with a method that is not supported. | 405 Method Not Allowed | Yes | Yes | Yes | |
The request contained an Accept header other than permitted media types, a character set other than UTF-8 or a version that was not supported | 406 Not Acceptable | Yes | Yes | Yes | |
The operation was refused because the payload is in a format not supported by this method on the target resource. | 415 Unsupported Media Type | Yes | No | No | |
The request was well formed but was unable to be processed due to business logic specific to the request | 422 Unprocessable Entity | If applicable to the HTTP method it is expected that this error will result in an error payload | Yes | Yes | No |
The operation was refused as too many requests have been made within a certain timeframe. | 429 Too Many Requests | Throttling is a NFR. The data holder should include a Retry-After header in the response indicating how long the data consumer must wait before retrying the operation. | Yes | Yes | Yes |
Something went wrong on the API gateway or micro-service | 500 Internal Server Error | The operation failed. | Yes | Yes | Yes |
Service is currently unavailable | 503 Service Unavailable | Yes | Yes | Yes | |
The server was unable to respond in a timely manner | 504 Gateway Timeout | Returned if a timeout has occurred but a resend of the original request is viable (otherwise use 500 instead) | Yes | Yes | Yes |
Payload Conventions
This section of the standard outlines the request and response payload structures for all API end points as well as the naming conventions for fields.
Request Payload Structure
A sample request would be structured as follows:
{
“data”: {
...
},
“meta”: {
...
}
}
Each API request payload MUST have a JSON object at the root level known as the root object. This object MUST contain a data
object to hold the primary data for the request.
The root object will contain a meta
object if, and only if, it is specifically REQUIRED by the end point. The meta object is used to provide additional information such as second factor authorisation data, traffic management, pagination counts or other purposes that are complementary to the workings of the API.
The definition of the contents for the data
object and meta
object will be defined separately for each end point.
Response Payload Structure
A sample successful response:
{
“data”: {
...
},
“links”: {
“self”: “...”
},
“meta”: {
...
}
}
A sample unsuccessful response:
{
“errors”: [
{
“code”: “...”,
“title”: “...”,
“detail”: “...”
}, {
“code”: “...”,
“title”: “...”,
“detail”: “...”,
“meta”: {
...
}
}
]
}
Each API response payload MUST have a JSON object at the root level known as the root object.
The contents of the root object are as follows:
- If the response is successful (200 OK) the root object:
- MUST contain a
data
object - MUST contain a
links
object - MAY contain a
meta
object if REQUIRED by the definition of the specific end point
- MUST contain a
- If the response is unsuccessful (not 200 OK) the root object:
- MAY contain an
errors
object (as per the specific end point definition)
- MAY contain an
The definition of the contents for the data
object and meta
object will be defined separately for each end point.
The links
object will contain links to related API end points. This will include links to support pagination.
The links object MUST contain a field named self
that will have the fully qualified URI to the current request as a value.
The errors
object is defined in the Error Codes section.
Field Naming Conventions
Valid Characters In Field Names
All field names defined in either a request or response payload MUST be treated as case sensitive by clients and servers, and they MUST meet all of the following conditions:
- Member names MUST contain at least one character.
- Member names MUST contain only the allowed characters listed below:
- U+0061 to U+007A, a-z
- U+0041 to U+005A, A-Z
- U+0030 to U+0039, 0-9
- Additionally, the following characters are allowed in field names, except as the first or last character:
- U+002D HYPHEN-MINUS, '-'
- U+005F LOW LINE, '_'
- U+0024 DOLLAR SIGN, '$'
Any other character MUST NOT be used in field names.
Field Naming Style
Field names MUST be meaningful names with defined semantics.
Fields representing the same data in different payloads or different parts of a payload MUST have the same name.
Array types SHOULD have plural field names. All other field names SHOULD be singular.
Field names MUST be defined using camel case with the following clarifications:
- If a field name is a single acronym it SHOULD be lowercase
- If a field name contains an acronym along with other words it MAY be uppercase
- The first character in a field name SHOULD be lower case unless it is part of an acronym
Fields MUST NOT be named using reserved javascript tokens.
Maps
For JSON maps (i.e. key/value pairs) any Unicode character MAY be used as a field name and stylistic requirements do not apply.
Field Property Conventions
Field Data Types
Each field defined for the payloads of an end point MUST have an assigned data type.
The list of valid data types are set out in the common field types section. If a custom data type is required for a field then the field SHOULD be classified as a string with a clear description of how the property value is to be interpreted or defined.
Mandatory/Optional Fields
Each field defined for the payloads of an end point MUST have an assigned status of mandatory, optional or conditional.
Mandatory fields MUST be present and have a non-null value in a request or response payload for the payload to be considered valid.
Optional fields MAY be present but this is not guaranteed. It is also valid for these fields to be present but have a null value. Note that optional fields indicate that data may sometimes not be held by a Data Holder and this is an expected scenario.
Conditional fields MUST have an associated conditional statement. If the conditional statement is true in a specific request or response the field is considered mandatory. If the conditional statement is false then the field is considered optional.
Empty/Null Fields
An empty field (ie. a field that is not present in a payload) will be considered equivalent with a field that is present with a null
value.
An empty string (“”
) is not considered to be equivalent to null
.
A Boolean value of false is not considered to be equivalent to null
. Optional Boolean fields, by implication, have three possible values: true, false and indeterminate (ie. null
).
Object conventions
Sample union object structure:
“data”: {
[
{
“shapeUType”: “circle”,
“circle”: {
}
},
{
“shapeUType”: “square”,
“square”: {
}
}
]
}
A specific convention will apply to union objects.
In the standards a union object is used in a situation where a set of data can be represented with different sets of fields depending on the context. To maintain strong typing of the fields one of a series of known object structures will be used. An example where this technique is used in the standard is in the definition of account balances where balance information can be represented differently, but unambiguously, for different account types.
For union objects an additional field, with a known suffix, is used to identify the object type that has been provided specifically.
As the name of this field is constant it can be used to perform an indirect lookup on the object type that has actually been provided removing the need to scan for which object is present.
A field of this type will always be specified with the suffix UType
meaning Union Type.
Array Conventions
Samples for providing array values:
## Many-values:
"middleNames": ["Geoff", "John"],
"errors": [
{
"code": "...",
"title": "...",
"detail": "..."
}, {
"code": "...",
"title": "...",
"detail": "..."
}
]
## Single-value:
"middleNames": ["Geoff"],
"errors": [
{
"code": "...",
"title": "...",
"detail": "..."
}
]
## Empty array:
"middleNames": [ ],
"errors": [ ]
Unless otherwise stated within the data standards, arrays are explicitly expressed in response payloads.
Mandatory fields
In objects where an array field is defined as having 0..n values, the array field must be explicitly expressed as an array in the payload, even if it only contains one item or is empty.
This applies equally for object arrays. Where a field is defined as an array value, the response should be:
- an array of objects,
- an array of values, or
- an empty array (
[]
).
An empty array is the representation for an array equivalent to an empty string.
Optional fields
If the field is optional a null
value or omission of the field in the response is accepted.
Normative references
The only exception to this, unless explicitly stated, is normative standards. The requirements for expressing arrays within those normative standards apply per the normative references.
Common Field Types
Properties defined in response schemas with enumerated values will now correctly show the type as 'Enum' instead of 'string'
The following table outlines the common data types for fields used in the standard.
Type | Description | Valid Examples |
---|---|---|
String | Standard UTF-8 string but unrestricted in content. Any valid Unicode character can be used. | |
ASCIIString | Standard UTF-8 string but limited to the ASCII character set. | |
Boolean | Standard JSON boolean | true false |
Enum | String representing an option from a defined list of values - All possible values MUST be provided - Values MUST be in all caps - Spaces MUST be replaced with under bars '_' - Values MUST be limited to the ASCII character set |
“OPTION1” “ANOTHER_OPTION” “VAL_ABC_123” |
NaturalNumber | A natural number (ie. a positive integer inclusive of zero) | 0 1 10000 |
PositiveInteger | A positive integer (zero excluded) | 1 10000 |
NegativeInteger | A negative integer inclusive of zero | 0 -1 -10000 |
Integer | Any positive or negative integer inclusive of zero | 1 0 -1 |
Number | A standard floating point number. Can be positive, negative or zero | 0.1 -100.09 10 90.09 |
Base64 | Base64 encoded string as per [RFC4648] | Q29uc3VtZXIgRGF0YSBSaWdodA== |
DateTimeString | Combined Date and Time string as per [RFC3339] (labelled date-time in the RFC). As specified in [RFC3339] times MUST be offset relative to UTC | “2007-05-01T15:43:00.12345Z” “2012-12-25T15:43:00-08:00” “1997-01-12T15:43:00.121Z” |
DateString | Date string as per [RFC3339] (labelled full-date in the RFC) | “2007-05-01” “2012-12-25” |
TimeString | Time string as per [RFC3339] (labelled full-time in the RFC). As specified in [RFC3339] times MUST be offset relative to UTC | “15:43:00.12345Z” “15:43:00-12:00” |
CurrencyString | Standard 3 character currency codes as per ISO-4217 | “AUD” “USD” “GBP” |
RateString | A string representing a percentage (e.g. an interest rate). A rate of 100% would be represented by the value 1.0 and a rate of -100% by -1.0 - At least 1 and up to a total of 16 significant digits before decimal point - Up to 16 digits following the decimal point - No formatting, eg thousand separating commas |
“0.05”(=5%) “-0.05” (=-5%) “12.3456789” (=1234.56789%) “-99.123456789123” (=9912.3456789123%) |
AmountString | A string representing an amount of currency. - A positive, zero or negative number - Negative numbers identified with a ‘-‘ - Currency symbols MUST NOT be supplied - At least 1 and up to a total of 16 significant digits before decimal point - Minimum 2 digits following a decimal point (more digits allowable but only if required) - No additional formatting, eg thousand separating commas |
“0.01” “10.00” “1234567.89” “-1001.23” “1.999” |
MaskedPANString | Masked credit card number. Lower case ‘x’ MUST be used to mask numbers and only the last four digits MUST be exposed to facilitate identification. This type is expected to be used for display so the format MUST be logical for this context | "xxxx xxxx xxxx 1234" |
MaskedAccountString | Masked bank account number genericised for a variety of account types. MUST be represented as the full account number would normally be represented for display (including formatting) but with all digits except the last four replaced with a lowercase x. This type is expected to be used for display so the format MUST be logical for this context | "xxxx xxxx xxxx 1234" "xxx-xxx xxxxx1234" |
URIString | A valid URI | "http://www.google.com" |
ExternalRef | The format is defined by an external reference such as ISO standard or an RFC | Swift bank codes using ISO 9362 |
Pagination
Each API end point that can return multiple records will stipulate whether pagination is supported for the end point or not. For end points that will return less than a reasonably sized page of results in the majority of circumstances support for paging may not be included.
Note that the use of paging for an end point does not require or preclude the use of filtering query parameters. It is expected that filtering and paging will be applied independently of each other.
Query Parameters
The consumer will stipulate pagination requirements on the request using query parameters. When paging is supported the consumer MAY provide the following query parameters:
- page – the page number being requested (with the first page being 1)
- page-size – the number of records to return in each page
If the query parameters are not provided the following defaults will be assumed:
- page – a default of 1 (the first page) will be assumed
- page-size – a default of 25 will be assumed
Response Fields
In addition to the data requested a holder MUST provide the following additional information in the response payload:
- In the links object the following fields are to be provided:
- first - A URI to request the first page. Mandatory if this response is not the first page.
- last - A URI to request the last page. Mandatory if this response is not the last page.
- prev - A URI to the previous page. Mandatory if this response is not the first page.
- next - A URI to the next page. Mandatory if this response is not the last page.
- In the
meta
object the following fields are to be provided:- totalRecords - The total number of records in the set. This field MUST be present.
- totalPages - The total number of pages in the set. This field MUST be present. If totalRecords is 0 totalPages MUST be 0.
For each of these fields the page size specified in the request should be assumed when calculating values.
Additional Pagination Rules
- Holders are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.
- A maximum page size of
1000
records is assumed for all end points (unless otherwise stipulated in the end point definition). If a page size greater than this maximum is requested then an Invalid Page Size error SHOULD be returned.
Cursor Support
For performance reasons data holders may wish to support other pagination patterns such as cursors or continuation tokens. While the standard does not explicitly support these additional mechanisms it is considered allowable to implement these patterns and expose them via the pagination links.
In this scenario the URIs included in the links for other pages may not be compliant with the standard and may, instead, include other query parameters that support another pagination pattern. It is expected that all other pagination requirements such as link fields and meta fields will still be supported if other patterns are implemented.
To allow for a more performant implementation data consumers are encouraged to utilise pagination links wherever possible and only use constructed URIs for the first page or if random access to a specific set of records is required.
ID Permanence
Within these standards resource IDs are REQUIRED to comply with the following:
- An ID for a resource should only be specified in the API standard if an end point exists to obtain detail for that resource or to change the state of the resource.
- If an ID is specified in the standards for a resource then it is mandatory and MUST be supplied, by the data holder, in accordance with the standards.
- If an ID is specified the ID value MUST be entirely arbitrary and have no inherent meaning. For instance, an ID should not be a combination of other fields or a string that can be parsed to extract meaningful information.
- IDs SHOULD be unique but that uniqueness may be within a clearly bounded context. For example, a beneficiary ID may be unique but only in the context of a specific account. The bounds of uniqueness should be clearly described in the standards definition for the end point.
- IDs MUST be immutable across sessions and consents but MUST NOT be transferable across Data Recipient Software Products. For example, "Data Recipient Software Product "A" obtaining an account ID would get a different result from "Data Recipient Software Product B" obtaining the ID for the same account even if the same customer authorised the access. Under this constraint IDs cannot be usefully transferred between client organisations or data holders.
- IDs MUST NOT be transferable between different customers for the same Data Recipient Software Product. For example, a Data Recipient Software Product should obtain a different ID for a joint account if the ID was obtained independently using authorisations from both customers.
- In payloads the field name of “id” should NEVER be used. Each ID field should be meaningfully named so that wherever that ID is used across multiple end points it always refers to the same ID set. For instance, the IDs for accounts would be represented in JSON in a field named “accountId”.
Error Codes
These standards define a standard list of error codes that Data Recipient Software Products and Data Holders SHOULD or MUST conform to. Further,
- Data Recipient Software Products and Data Holders SHOULD use the standard error codes as defined
- Where a specific error code MUST be responded, this requirement is stated against the applicable error code or API endpoints
- Where a specific error code MAY be responded, this requirement is stated against the applicable error code or API endpoints
- Data Recipient Software Products and Data Holders MAY respond with application-specific error codes and in doing so, MUST respond with the
MetaError » urn
field populated with the standard CDR error code.
Error Response Structure
Non-Normative Example
{
"errors": [
{
"code": "urn:au-cds:error:cds-banking:Authorisation/UnavailableBankingAccount",
"title": "Unavailable Banking Account",
"detail": "808b5b1d-0798-4bdf-a3c8-f9cce2904eb2"
}
]
}
The errors
object will be an array of zero or more unnamed objects. The fields in each of these objects will be as follows:
code
field MUST be present: holds an end point specific error code. This MAY be a standard CDR error code or an application-specific error code.title
field MUST be present: holds a human readable label of the error that is constant percode
detail
field MUST be present: holds a human readable description of this specific errorisSecondaryDataHolderError
field MAY be present: an optional Boolean flag which indicates the error is propagated from a designated secondary data holdermeta
object MAY be present: holds additional end point specific data relevant to the error
If a Data Recipient Software Product or Data Holder responds with an application-specific error code, the standard CDR URN error code MUST be provided in the MetaError
object.
URN Structure
When responding with a standard CDR error code, the URN structure is defined as follows:
urn-string = "urn:" NID ":" metatype ":" sub-type ":" error-category "/" error-code
- NID = "au-cds" string.
- metatype = "error" string.
- sub-type = cds-all / cds-register / cds-banking / cds-energy
- cds-all = "cds-all" string. An error code common to all API responses,
- cds-register = "cds-register" string. Reserved for CDR Register issued error codes only,
- cds-banking = "cds-banking" string. An error code specific to the CDR banking APIs only,
- cds-energy = "cds-energy" string. An error code specific to the CDR energy APIs only.
- error-category = string. The high-level category code for the error defined in the Consumer Data Standards
- error-code = string. The specific error encountered, defined in the Consumer Data Standards
Standard Error Codes
A list of standard error codes to help categorise an error response. The applicable HTTP response code is also given.
General Errors
Non-Normative Example
# A request to a Data Holder extension API is made where an application-specific error is returned
#
# Request
POST https://data.acme.com.au/cds-au/v1/banking/ACME-new-loan-application HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-ACME-v : 7
# Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"code": "ACME-APPLY-017",
"title": "Application Is Missing Product ID",
"detail": "A new loan application was requested but the product ID was not provided",
"meta": {
"urn": "urn:au-cds:error:cds-all:GeneralError/Expected"
}
}
]
}
400 Bad Request Errors
Non-Normative Example
# A request to Get Accounts is made however
# the value of is-owned is not a Boolean value
#
# Request
GET https://data.holder.com.au/cds-au/v1/banking/accounts?is-owned=2007-05-01 HTTP/1.1
Host: data.holder.com.au
Accept: application/json
# Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"code": "urn:au-cds:error:cds-all:Field/Invalid",
"title": "Invalid Field",
"detail": "is-owned"
}
]
}
Error Title | Error Code | Description |
---|---|---|
Missing Required Field | urn:au-cds:error:cds-all: |
The request is missing a mandatory field required for the API. It MAY be a missing query parameter or missing field in the request payload. This error code can be used, where a more specific validation error is not applicable. The error detail SHOULD be the parameter name of the missing field.This error code MUST be supported for unauthenticated and authenticated APIs. |
Missing Required Header | urn:au-cds:error:cds-all: |
A required HTTP header has not been provided. The error detail SHOULD be the HTTP header name.This error code SHOULD be supported for unauthenticated and authenticated APIs. |
Invalid Field | urn:au-cds:error:cds-all: |
Applies when the value of the URL parameter or request body parameter is an invalid type or the value violates the field's constraints as defined by the interface contract. For example, is-owned is a Boolean but a DateString value is provided.The error detail SHOULD be the parameter name of the invalid field. The error detail MAY include further details explaining the valid format.This error code MUST be supported for unauthenticated and authenticated APIs. |
Invalid Header | urn:au-cds:error:cds-all: |
Applies when a HTTP Header is provided but the value provided is an invalid type or violates the field type constraints as defined in the Consumer Data Standards. The error detail SHOULD be the HTTP header name. The error detail MAY include further details explaining the valid format.This error code SHOULD be supported for unauthenticated and authenticated APIs. |
Invalid Date | urn:au-cds:error:cds-all: |
An invalid date is provided. For example, a future date value is expected, but a date in past or current date is supplied. Applies to DateTimeString , DateString , and TimeString field types.The error detail SHOULD be the parameter name of the invalid date field. The error detail MAY include further details explaining the expected date value.This error code MUST be supported for unauthenticated and authenticated APIs. |
Invalid Page Size | urn:au-cds:error:cds-all: |
The value provided in the page-size pagination field is greater than the maximum allowed by the Consumer Data Standards (page-size > 1000 ).This error code MUST be supported for unauthenticated and authenticated APIs. |
Invalid Version | urn:au-cds:error:cds-all: |
A request is made for a version that is not a PositiveInteger .For example:
This error code MUST be supported for unauthenticated and authenticated APIs. If the version header is a PositiveInteger but is not a version supported by the Data Holder, the Unsupported Version code applies. |
403 (Forbidden) Errors
404 (Not Found) Errors
Non-Normative Examples
# A request to a resource endpoint that does not exist
#
# Request
GET https://data.holder.com.au/cds-au/v1/banking/payments/294819e6-7ae0-4e20-900a-6a733fd97854/location HTTP/1.1
Host: data.holder.com.au
Accept: application/json
# Response
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"code": "urn:au-cds:error:cds-all:Resource/NotFound",
"title": "Resource Not Found"
}
]
}
# A request to a resource endpoint that exists in the data standards,
# but is not currently implemented
#
# Request
POST https://data.holder.com.au/cds-au/v1/admin/register/metadata HTTP/1.1
Host: data.holder.com.au
Accept: application/json
# Response
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"code": "urn:au-cds:error:cds-all:Resource/NotImplemented",
"title": "Resource Not Implemented"
}
]
}
#
# A request to a resource that is temporarily unavailable
#
# Request
GET https://data.holder.com.au/cds-au/v1/banking/accounts/b3f0c9d0/transactions/52e443ae13c5 HTTP/1.1
Host: data.holder.com.au
Accept: application/json
# Response
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"code": "urn:au-cds:error:cds-all:Resource/Unavailable",
"title": "Unavailable Resource",
"detail": "52e443ae13c5"
}
]
}
#
# A request to a get a banking account that is invalid
#
# Request
GET https://data.holder.com.au/cds-au/v1/banking/accounts/invalid-id/ HTTP/1.1
Host: data.holder.com.au
Accept: application/json
# Response
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"code": "urn:au-cds:error:cds-banking:Authorisation/InvalidBankingAccount",
"title": "Invalid Banking Account",
"detail": "invalid-id"
}
]
}
406 (Not Acceptable) Errors
422 (Unprocessable Entity) Errors
Non-Normative Example
#
# A bulk request to a get a banking account that is unavailable
#
# Request
POST https://data.holder.com.au/cds-au/v1/banking/accounts/balances HTTP/1.1
Host: data.holder.com.au
Accept: application/json
{
"data": {
"accountIds": [
"b3f0c9d0-457d-4578-b0cd-52e443ae13c5",
"b1bccd84-d29a-4233-8e44-be01c74eb85b"
]
},
"meta": {}
}
# Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "urn:au-cds:error:cds-all:Authorisation/UnavailableBankingAccount",
"title": "Unavailable Banking Account",
"detail": "b3f0c9d0-457d-4578-b0cd-52e443ae13c5"
}
]
}
CDR Register Errors
The following error codes apply to responses from the CDR Register. Data Recipient Software Product and Data Holder clients requesting data from the CDR Register MAY expect the following standard CDR error codes to be encountered:
Processing Errors
When a server encounters multiple problems for a single request, the most generally applicable HTTP error code SHOULD be used in the response. For instance, 400 Bad Request
might be appropriate for multiple 4xx errors or 500 Internal Server Error
might be appropriate for multiple 5xx errors.
A server MAY choose to stop processing as soon as a problem is encountered, or it MAY continue processing and encounter multiple problems. For instance, a server might process multiple attributes and then return multiple validation problems in a single response.
Extensibility And Application Specific Errors
Error handling has been designed with extensibility in mind. Where an application supports error codes specific to that implementation, it is intended that implementations can extend the standard CDR error codes with application-specific error responses whilst maintaining interoperability for clients.
Non-Normative Example
# Application-specific error code extends a standard CDR error code with
# details specific to the Data Holder
{
"errors": [
{
"code": "acme-bank:JointAccountElectionRemoved",
"title": "Joint Account Consent Election Is Removed",
"detail": "Description of the specific error encountered",
"meta": {
"urn": "urn:au-cds:error:cds-banking:Authorisation/UnavailableBankingAccount"
}
}
]
}
To assist clients, the Data Recipient Software Product or Data Holder MUST provide the application-specific error code in the ResponseErrorListV2 » code
and the standard CDR error code in the ResponseErrorListV2 » MetaError » urn
field denoting the standard error code the implementation extends.
Transition arrangements
Non-Normative Examples
# Application-specific error code before transition
{ "errors": [
{
"code": "old error code",
"title": "error message",
"detail": "Description of the specific error encountered"
}
] }
# Application-specific error code during transition
{ "errors": [
{
"code": "old error code",
"title": "error message",
"detail": "Description of the specific error encountered",
"meta": {
"urn": "urn:au-cds:error:cdr-all:Header/UnsupportedVersion"
}
}
] }
# Standardised-error code after retirement of application-specific error code
{ "errors": [
{
"code": "urn:au-cds:error:cdr-all:Header/UnsupportedVersion",
"title": "Unsupported Version",
"detail": "'x-v' **MUST** be greater than or equal to '2'"
}
] }
If Data Recipient Software Products or Data Holders support custom error codes prior to February 1st 2022, the following transition arrangements apply:
Effective as soon as standardised error codes are supported by the Data Recipient Software Product or Data Holder:
- If the Data Recipient Software Product or Data Holder supports application-specific error codes they MUST publish a mapping of those codes to the standard CDR error codes in a developer friendly way that is discoverable and freely available.
- Data Recipient Software Products and Data Holders MAY publish this mapping any time prior to February 1st 2022.
Effective from February 1st 2022: Data Holders and Data Recipient Software Products MUST support standardised error codes by this date and continue to support any custom error codes.
- Standardised error codes MUST be provided in the
ResponseErrorListV2 » MetaError » urn
field - If applicable, application specific error codes MUST be provided in the
ResponseErrorListV2 » code
- Data Recipient Software Products and Data Holders MAY phase their transition to support standardised error codes such as by endpoint or per error code if preferred prior to this date.
- Standardised error codes MUST be provided in the
Effective from November 1st 2022: Data Holders and Data Recipient Software Products MAY deprecate any custom error codes
- Standardised error codes MAY be provided in the
ResponseErrorListV2 » code
field if no application-specific error code applies - Application-specific error codes MAY be provided in the
ResponseErrorListV2 » code
- Standardised error codes MAY be provided in the
Extensibility
The Consumer Data Right standards will not cover all possible data sets or APIs that participants may wish to expose. Participants may also wish to innovate on top of the API standards by offering additional data to meet specific market opportunities. It is desirable that the standards not only allow for this to occur but actively encourage it with specific additions to the standards to enable such extension.
At the same time, it is important that a participant seeking to provide extensions does not hinder a data consumer that is only built for the published standards.
To accommodate these concerns the standards incorporate the following considerations specifically related to extension by data holders.
The three types of extension that the standards address are:
- Data holder offering entirely new API categories that are not covered by the API Standards
- Data holder offering additional end points to an API category that is already covered by the standards
- Data holder offering additional fields to the response payloads for an end point defined in the standards
Holder Identifier
For example, the prefixes for the four major Banks included in the first phases of implementation would be:
- CBA – Commonwealth Bank
- WBC – Westpac Banking Corporation
- ANZ – ANZ Banking Group
- NAB – National Australia Bank
Data holders seeking to extend the standards MUST nominate a prefix to identify all extensions. Extended fields and end points and would use this prefix consistently. This prefix would be, by preference, the ASX symbol for the holder. Care should be taken not to use a prefix already adopted by another holder in the regime.
In these standards, where a Holder Identifier would be included, the term <HID>
will be used.
New API Categories
When extending by adding new API categories a holder MUST add these to the overall URI structure by substituting the industry element with the Holder (Provider) ID.
For instance, the standard URI base path is structured as:
https:// <holder-path> / cds-au / <version> / <industry> / <resource>
For the extension API categories for a specific holder they would be structured as:
https:// <holder-path> / cds-au / <version> / <HID> / <resource>
The end points defined under this structure, including the payloads of these end points do not need to be prefixed in any way. The fact that they are underneath the holder section implies that they are additional to the standard.
Note that:
- This mechanism MUST NOT be used to create modified duplicates of the end points defined in the API Standards
- The end points in this area MUST comply with the standard's conventions and principles including naming conventions and data types.
New End Points In Existing API Categories
When creating new end points that are in parallel to existing API categories in the standard the Holder Identifier MUST be used to prefix the highest URI element where divergence occurs.
For example, assume an existing balance end point is defined as follows:
<base-path>/accounts/{account ID}/transactions
and the holder wishes to add an end point that summarises balance movement for a specific time period then they may define the end point as:
<base-path>/account/{account ID}/<HID>-balance-movement
Note that:
- The prefix is defined as the Holder Identifier followed by a hyphen.
- As the entire end point is new, the request and payload fields do not need to be prefixed in any way.
- Care should be taken to ensure there is no collision with an end point defined in the standards by specifying an extension at the same level as a variable URI element (such as at the same level of the {account ID} in the example above).
- If an end point has multiple levels in the resource path only the highest point where divergence with the standard occurs needs to be prefixed.
- The new end point MUST comply with standard's conventions and principles including naming conventions and data types.
Additional Fields In An Existing Response Payload
When adding a new field in an existing payload the field can be added to the JSON by prefixing the string <HID>-
.
If an object is being added as an extension only the highest level object name needs to be prefixed. Any fields inside the extended object can be named normally.
Note that:
- Existing fields MUST NOT be modified in any way. This includes adding new enumeration values to enum type fields.
- A mandatory field MUST NOT be made optional as the result of an extension.
- Request payloads can also be extended but the resulting end point should still execute successfully if the extension field is not present (by implication, extension fields in request payloads MUST be optional).
- New query parameters MAY be added along the same lines as a new field in a request payload (i.e. prefixed, non-mandatory and no side effects if not present).
- New headers MAY be added along the same lines as a new field in a request payload with the exception that the new header should be prefixed
x-<HID>-
. - New fields MUST comply with the naming conventions and data type standards used.
Additional Query Parameters
When adding support for a new query parameter to an existing end point that a data consumer is expected to supply, the new parameter should be prefixed by the string <HID>-
to avoid potential collision with extension by another data holder.
Extension Versioning
As described previously in the versioning section the standard provides for multiple versions of each API end point. This implies the need for extensions to also be versioned.
An optional header x-<HID>-v
will be supported for all end points that can be used by the data consumer to request a specific version of extension fields to include in the response. See the section on HTTP Headers for more information on the use of this header.
Consumer Experience
The Consumer Experience (CX) Standards contain requirements for the creation of implementations by both Data Recipients and Data Holders. The full list of CX Standards can be found below.
The CX Guidelines provide examples and recommendations for how to implement key rules and standards that relate to the consumer experience. They can be accessed along with additional CX commentary from the CX Guidelines page.
Data Language Standards: Common
Example of data language standards presented in a consumer-facing interaction, where [1] refers to Data cluster language, and [2] refers to Data permission language.
In accordance with CDR Rule 8.11 (1)(d), a data standard must be made to provide descriptions of the types of data to be used by CDR participants in making and responding to requests. Adherence to this language will help ensure there is a consistent interpretation and description of the consumer data that will be shared across different CDR implementations.
Area | CX Standard |
---|---|
Data Language Standards: Language to be used | Data Recipients and Data Holders MUST use data language standards to describe data clusters and permissions in consumer-facing interactions. See the Banking Language section for language to be used when requesting banking data; and the Energy Language section for language to be used when requesting energy data. Data language standards MUST be used when CDR data is being requested, reviewed, or access to such data is withdrawn. Data Recipients and Data Holders MUST use the appropriate data standards language for business consumers as denoted with an '*' for the relevant data. Data Recipients and Data Holders SHOULD expand on the proposed language where appropriate to communicate further details of what is being shared. Additional details MAY include additional information in context, such as in-line help or tool tips, and/or additional permissions where they may exist. Examples of permission details that MAY be used and provided as in-line help are denoted with an '†' for the relevant data. |
Data Language Standards: Detailed scope requests | If a scenario requires it, Data Holders and Data Recipients MUST merge and amend Basic and Detailed data cluster and permission language to show that Detailed scopes include Basic data. Data Holders and Data Recipients MUST use the alternative language denoted with an '‡' for the relevant scope(s). See the Banking Language section for banking data and the Energy Language section for energy data. Example: A Data Recipient presents the Detailed data cluster in a data request to a consumer, but does not present the Basic data cluster. The Detailed scope includes Basic data, but this is not apparent to the consumer based on the data cluster language and permissions used for the Detailed scope. |
Customer Language: Common
See below for the customer data language standards, which are common across all sectors.
Individual Consumer
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Name and occupation | Name Occupation |
common:customer.basic:read |
Contact Details | Phone; Email address; Mail address; Residential address; |
common:customer.detail:read |
Name, occupation, contact details ‡ | Name; Occupation; Phone; Email address; Mail address; Residential address; |
common:customer.detail:read |
Business consumer
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Organisation profile * | Agent name and role; Organisation name; Organisation numbers (ABN or ACN);† Charity status; Establishment date; Industry; Organisation type Country of registration; |
common:customer.basic:read |
Organisation contact details * | Organisation address; Mail address; Phone number; |
common:customer.detail:read |
Organisation profile and contact details *‡ | Agent name and role; Organisation name; Organisation numbers (ABN or ACN),† Charity status; Establishment date; Industry; Organisation type; Country of registration; Organisation address; Mail address; Phone number; |
common:customer.detail:read |
Profile Scope and Standard Claims: Common
In accordance with [OIDC] section 5.4 and section 5.5, this language refers to the [OIDC] profile
scope and request of individual claims for the authenticated End-User.
Data cluster language | Permission language |
Authorisation Scopes | Required |
---|---|---|---|
Name | Full name and title(s) | OIDC Profile scope or one or more of these standard [OIDC] claims*:name given_name family_name updated_at *See 5.4. Requesting Claims using Scope Values on the OIDC website for more information. |
Required |
Contact Details | Phone number; Email address; Mail address; |
One or more of these standard [OIDC] claims*:email email_verified phone_number phone_number_verified address *See 5.4. Requesting Claims using Scope Values on the OIDC website for more information. |
Optional |
Note: For non-individual consumers, claims available via the profile scope will only return the details of the authenticated End-User and not the organisation or non-individual consumer.
Banking Language
Banking Accounts
See below for the data language standards for the banking account scopes:
Data cluster language | Permission language |
Authorisation Scopes |
---|---|---|
Account name, type and balance | Name of account; Type of account; Account balance; |
bank:accounts.basic:read |
Account numbers and features | Account number; Interest rates; Fees; Discounts; Account terms; Account mail address; |
bank:accounts.detail:read |
Account balance and details‡ | Name of account; Type of account; Account balance; Account number; Interest rates; Fees; Discounts; Account terms; Account mail address; |
bank:accounts.detail:read |
Transactions
See below for the data language standards for the banking transactions scope:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Transaction details | Incoming and outgoing transactions; Amounts; Dates; Descriptions of transactions; Who you have sent money to and received money from; (e.g. their name)† |
bank:transactions:read |
Regular Payments
See below for the data language standards for the regular payments scope:
Data cluster language | Permission language |
Authorisation Scopes |
---|---|---|
Direct debits and scheduled payments | Direct debits; Scheduled payments; |
bank:regular_payments:read |
Payees
See below for the data language standards for the payees scope:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Saved payees | Names and details of accounts you have saved; (e.g. their BSB and Account Number, BPAY CRN and Biller code, or NPP PayID)† | bank:payees:read |
Energy Language
Energy Accounts
See below for the data language standards for the energy accounts scopes:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Accounts and plans | Account and plan information; | energy:accounts.basic:read |
Account and plan details | Account type; Fees, features, rates, and discounts; Additional account users; |
energy:accounts.detail:read |
Account and plan details ‡ | Account and plan information; Account type; Fees, features, rates, and discounts; Additional account users; |
energy:accounts.detail:read |
Concessions
See below for the data language standards for the concession scope:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Concessions and assistance | Concession type; Concession information; |
energy:accounts.concessions:read |
Payments
See below for the data language standards for the payments schedule scope:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Payment preferences | Payment and billing frequency; Any scheduled payment details; |
energy:accounts.paymentschedule:read |
Billing
See below for the data language standards for the billing scope:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Billing payments and history | Account balance; Payment method; Payment status; Charges, discounts, credits; Billing date; Usage for billing period; Payment date; Invoice number; |
energy:billing:read |
NMI Standing Data
See below for the data language standards for the NMI standing data scopes:
Data cluster language | Permission language |
Authorisation Scopes |
---|---|---|
Electricity connection | National Meter Identifier (NMI); Customer type; Connection point details; |
energy:electricity.servicepoints.basic:read |
Electricity meter | Supply address; Meter details; Associated service providers; |
energy:electricity.servicepoints.detail:read |
Electricity connection and meter ‡ | National Meter Identifier (NMI); Supply address; Customer type; Connection point details; Meter details; Associated service providers; |
energy:electricity.servicepoints.detail:read |
Distributed Energy Resources (DER)
See below for the data language standards for the Distributed Energy Resources (DER) scope:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Energy generation and storage | Generation information; Generation or storage device type; Device characteristics; Devices that can operate without the grid; Energy conversion information; |
energy:electricity.der:read |
Electricity Usage
See below for the data language standards for the electricity usage scope:
Data cluster language | Permission language | Authorisation Scopes |
---|---|---|
Electricity usage | Usage; Meter details; |
energy:electricity.usage:read |
Accessibility Standards
Area | CX Standard |
---|---|
Accessibility | At a minimum, all CDR participants MUST seek to comply with the following accessibility guidelines throughout the Consent Model. These standards SHOULD be assessed, tested, and refined further by accessibility consultants directly involved in implementation. |
Accessibility Content distinction |
Data Recipients and Data Holders MUST seek to have all aspects of the Consent Model comply with WCAG 1.4. This will make it easier to see and hear content, including separate foreground information from the background. |
Accessibility Keyboard functionality |
Data Recipients and Data Holders MUST seek to have all aspects of the Consent Model comply with WCAG 2.1. This will make all functionality available from a keyboard. |
Accessibility Pointer interactions |
Data Recipients and Data Holders MUST seek to have all aspects of the Consent Model comply with WCAG 2.5. This will make it easier to operate functionality using various input devices |
Accessibility Reading experiences |
Data Recipients and Data Holders MUST seek to have all aspects of the Consent Model comply with WCAG 3.1. This will make text content readable and understandable |
Accessibility Input assistance |
Data Recipients and Data Holders MUST seek to have all aspects of the Consent Model comply with WCAG 3.3. This will help users avoid and correct mistakes. |
Consent Standards
Area | CX Standard |
---|---|
Consent: Redirection |
Data recipients MUST notify consumers of redirection prior to authentication. |
Disclosure consent: Collection source |
In the course of seeking a consumer’s consent to disclose data as part of a disclosure consent:
|
Disclosure Consent: Descriptions of Data to be Collected and Disclosed | If:
|
Disclosure Consent: Insight Descriptions
The standards in this section outline insight description requirements that apply where an insight disclosure consent is being sought and may also feature in CDR Receipts and Dashboards. These standards do not alter any existing rules obligations for CDR receipts or dashboards.
Note: The use of the term ‘data recipients’ to refer to accredited data recipients is consistent with the data standards nomenclature. Where these standards refer to ‘data recipient’, this should not be taken to mean a non-accredited person or trusted adviser.
Area | CX Standard |
---|---|
Insight disclosure: Insight comprehension |
Data recipients MUST use plain and concise language to describe what an insight would reveal or describe. Where possible and practical, the actual insight SHOULD be displayed to the consumer prior to the insight being disclosed. Where it is not possible to display the actual insight, accredited data recipients SHOULD include an example of the insight that demonstrates what the insight may reveal or describe. Accredited data recipients SHOULD make clear that any such examples are hypothetical. |
Insight disclosure: Insight timing |
Data recipients MUST specify the period the insight will refer to and MAY note when the insight will be or is expected to be generated. |
Insight disclosure: Purpose of insight |
Data recipients SHOULD explain the purpose of generating the insight. |
Insight disclosure: Insight generation |
Data recipients MAY explain how the insight will be generated using plain and concise language, which MAY include:
|
Disclosure Consent: Non-Accredited Person Disclosure Notification
The standards in this section outline requirements that apply when a disclosure consent is being sought to disclose data to a non-accredited person, which includes insight disclosure consents and trusted adviser disclosure consents.
These standards will feature where such a disclosure consent is being sought and may, as stated in any accompanying notes, also feature in CDR Receipts and Dashboards.
Note: The use of the term ‘data recipients’ to refer to accredited data recipients is consistent with the data standards nomenclature. Where these standards refer to ‘data recipient’, this should not be taken to mean a non-accredited person or trusted adviser.
Area | CX Standard |
---|---|
Disclosure consent: CDR protections |
Data recipients MUST state that data disclosed to a non-accredited person will not be regulated as part of the Consumer Data Right. Data recipients MAY include a plain and concise explanation of what this means, which MAY include information on the Consumer Data Right, and MAY include a link to the Office of the Australian Information Commissioner guidance on the Consumer Data Right. |
Disclosure consent: Review |
Data recipients MUST advise the consumer to review how the non-accredited person will handle their data. |
Disclosure consent: Data handling |
If available, data recipients MAY include a link to any relevant data handling policies of the non-accredited person, such as their Privacy Policy. |
Disclosure consent: Complaints |
Data recipients MUST provide plain and concise information on dispute resolution and making a complaint. This SHOULD reflect the process and information contained in the data recipient’s CDR policy related to complaints. This MAY also include a link to the accredited data recipient’s CDR policy. |
Disclosure consent: Insight records |
When seeking an insight disclosure consent, data recipients MUST provide instructions for how the consumer can access further records, including the actual insights (as per Rules 1.14 and 9.5). |
Disclosure consent: Notification record |
Data recipients MUST provide the information contained in the disclosure notification otherwise than in the consent flow. This SHOULD be contained in the consumer’s CDR Receipt. This SHOULD also be accessible in the consumer dashboard as part of the data sharing arrangement details. Note 1: The information to be included is limited to the following standards: CDR Protections; Review; Data Handling; Complaints; and Insight Records. The scope of information to include will depend on the accredited person’s specific implementation. Note 2: This standard does not alter any existing rules obligations for CDR receipts or dashboards. |
Authentication Standards
Area | CX Standard |
---|---|
Authentication: 'One Time Password' (OTP) |
Data Holders and Data Recipients MUST clearly refer to a "One Time Password" in consumer-facing interactions and communications. The use of the term "One Time Password" MAY be presented alongside an existing term used by a data holder (e.g. Netcode, one time pin etc.). |
Authentication: Passwords |
Data Holders and Data Recipients MUST state in consumer-facing interactions and communications that services utilising the CDR do not need access to consumer passwords for the purposes of sharing data. The exact phrasing of this is at the discretion of the Data Holder and Data Recipient. |
Authentication: Password link |
Data Holders MUST NOT include forgotten details links in redirect screens. The inclusion of such links is considered to increase the likelihood of phishing attacks. |
Authentication: OTP expiry |
Data Holders MUST communicate the expiry period of the OTP to the consumer in the authentication flow. |
Authorisation Standards
Area | CX Standard |
---|---|
Authorisation: Account selection |
Data holders MUST allow the consumer to select which of their accounts to share data from if the data request includes account-specific data and if there are multiple accounts available. The Data holder MAY omit this step if none of the data being requested is specific to an account (e.g. Saved Payees). |
Authorisation: Account selection functionality |
Data holders MAY include additional functionality to support account discovery and selection where further navigation or interaction is required to view all accounts. This may, for example, include search, sort, filter, scroll, grouping, and pagination, or other controls in line with existing consumer experiences. Any such functionality MUST NOT introduce unwarranted friction. Note: Unwarranted friction should have regard to CDR Rule 4.24 and is considered to include the addition of any requirements beyond normal data holder practices for an equivalent account selection process. |
Authorisation: Profile selection |
Data holders MAY add a 'profile selection' step or equivalent prior to the account selection step if a single identifier provides access to different customer accounts. For example, one customer ID may give access to business customer and individual customer accounts. The 'profile selection' step SHOULD only be considered if it is an existing customer experience, and SHOULD be as minimal as possible to avoid introducing unwarranted friction (having regard to CDR Rule 4.24). |
Authorisation: Account confirm |
Data holders MUST show which accounts the data is being shared from prior to confirming authorisation if the data request includes account-specific data. The data holder MAY omit this information if none of the data being requested is specific to an account (e.g. Saved Payees). |
Authorisation: Pending status |
Where an account requires further actions or approvals before data can be disclosed, data holders MUST indicate this to the user visually and MUST provide an explanation of what is required or expected. This MAY, for example, be achieved with a visual icon to indicate that the account is 'pending'. This indication MUST be accompanied by an in-context explanation to describe what the status means. This explanation SHOULD include any required actions and any specified time frames. |
Unavailable Accounts: Displaying accounts |
If certain accounts are unavailable to share, data holders SHOULD show these unavailable accounts in the account-selection step. Data holders SHOULD communicate why these accounts cannot be selected, and this SHOULD be communicated as in-line help or as a modal to reduce on-screen content. Data holders MAY provide instructions on how to make these accounts available to share, and this SHOULD be communicated as in-line help or as a modal to reduce on-screen content. Note: Unavailable accounts are to be interpreted in accordance with the rules on eligible consumers and required consumer data. |
Unavailable Accounts: No accounts can be shown |
If unavailable accounts cannot be shown in the account selection step, data holders MAY display a generic explanation and instructions. |
Unavailable Accounts: Authorisation not permitted |
If a successfully authenticated user cannot proceed to establish an authorisation in accordance with the rules on eligible consumers and required consumer data, data holders MAY provide the option of concluding the authorisation process. |
Unavailable Accounts: Request sharing rights |
If a user does not have sharing rights for a particular account or set of accounts, data holders MAY invite the user to request sharing rights from the authorisation flow. The presentation of this mechanism MUST NOT introduce unwarranted friction as defined in rule 4.24 on restrictions. |
Amending Authorisation Standards
Area | CX Standard |
---|---|
Authorisation: Amending consent |
The following standards apply when a Data Holder invites a CDR consumer to amend a current authorisation as per rule 4.22A and the ADR has supplied a cdr_arrangement_id: |
Customer Profile | Where customer profile selection applies, Data Holders SHOULD omit the profile selection step and assume the customer profile associated with the existing authorisation. Data Holders MAY indicate which profile the authorisation relates to during the authorisation process. |
Account Selection | Where account selection applies, Data Holders MUST pre-select accounts that were associated with the previous authorisation provided these accounts remain eligible and available to share. Data Holders MAY allow these accounts to be amended, and MAY provide information regarding the pre-selection of accounts. |
Changing Attributes | Data Holders MUST indicate where a dataset is being added to an authorisation or a disclosure duration is being amended. Data Holders MAY apply this standard to other changing attributes, but this MUST ONLY apply where the attribute in the new authorisation differs to that of the previous authorisation. How a changed attributed is signified is at the Data Holder’s discretion. |
Refer also to Future Dated obligations
Notification Standards
The standards in this section apply where a relevant joint account holder is about to take an action that may or, where a data holder leverages rule 4A.15 and allows a vulnerable joint account holder to share joint account data as if it were from an individual account, may not result in the other joint account holder(s) being notified.
Notifications: Joint Account Alerts
Area | CX Standard |
---|---|
Joint account notifications: Contextual alert |
Data holders MUST alert a joint account holder where an action they are about to perform may result in the other joint account holder(s) being notified. This standard applies to the authorisation flow, consumer dashboards, and the disclosure option management service where notifications to the other joint account holder(s) may be triggered. The precise wording of this notification is at the discretion of the data holder. |
Joint account notifications: Rule 4A.15 exemptions |
Where rule 4A.15 is leveraged to allow a vulnerable requester to share their joint account data as if it were an individual account, the data holder MUST alert the requester, in the context of the authorisation flow, that the other joint account holder(s) will not be notified. This alert SHOULD be applied where appropriate for joint account management in general, including the consumer dashboard and the Disclosure Option Management Service (DOMS). |
Joint account notifications: Further information |
In relation to the joint account alert standards in this section, data holders MAY provide further information about any services or processes in place for supporting vulnerable consumers or reporting risks of physical, psychological, or financial harm or abuse to the data holder. |
Alternative Notification Schedules for Joint Accounts
Rule 4A.14(3) requires data holders to (a) provide for alternative notification schedules (including reducing the frequency of notifications or not receiving notifications) and (b) give each joint account holder a means of selecting such an alternative, and of changing an election.
Alternative settings under 4A.14(3) only apply to the following notifications in 4A.14(1):
- The requester has given, amended, or withdrawn an authorisation
- Expiration of an authorisation
- A relevant account holder hasn't given approval within the relevant time frame
- A relevant account holder has withdrawn an approval
The standards in this section provide a non-exhaustive list of options that data holders may implement to support their compliance with these rules. The specific implementation of an alternative notification schedule and offering, which may or may not include options listed here, are at the data holder's discretion. It is the data holder's responsibility to ensure it is meeting its obligations under the CDR Rules. Compliance with the CDR Rules on alternative notification schedules would require, at a minimum, implementation of a combination of options (being a combination of options listed below, other measures, or both).
Area | CX Standard |
---|---|
Joint account notifications: Reduced frequency |
Data holders MAY offer consumers the ability to receive their joint account notifications less frequently and as a periodic summary. This MAY, for example, outline all joint account activity at a frequency determined by the data holder and consumer, such as the previous quarter, month, fortnight, and so on. This MAY also, for example, be provided with or in relation to other CDR notifications such as a CDR Receipt, which is optional for data holders. |
Joint account notifications: Granular control |
Data holders MAY offer consumers the ability to specify which joint account notifications they do and do not want to receive. This MAY, for example, allow a relevant joint account holder to only receive notifications when the requester gives or amends an authorisation. |
Joint account notifications: Turn off notifications |
Data holders MAY allow consumers to elect to no longer receive any joint account notifications. |
Joint account notifications: Consequences of amendment |
Data holders MAY inform the consumer of the consequences of amending their joint account notification schedule. This notification MAY include instructions for how to amend this schedule or reverse the amendment. |
Joint account notifications: Contextual amendment |
Data holders MAY provide a mechanism or entry point for a notification schedule to be amended from or in relation to the notification itself. This MAY, for example, allow a consumer to stop receiving the type of notification(s) from the notification itself. The notification MAY also, for example, include a link to amend the notification schedule or instructions to direct the consumer to the appropriate place. |
Joint account notifications: Amendment channels |
Data holders MAY allow a consumer to amend their notification schedule in line with existing notification management channels and experiences. This MAY, for example, allow the joint account notification schedule to be amended in the same location as other notifications. |
Joint account notifications: Notification content |
For the content of the approval notification, data holders MAY provide the consumer with instructions for how any relevant authorisation(s) or approval(s) can be reviewed. |
Withdrawal Standards
Area | CX Standard |
---|---|
Withdrawing consent | If a Data Recipient does not have a general policy to delete redundant data, and the consumer has not already requested that their redundant data be deleted:
|
Withdrawing authorisation: Consequences |
As part of the withdrawal process, the data holder MUST advise the consumer to review the consequences of withdrawal with the Data Recipient before they stop sharing their data. The data holder MAY consider using or paraphrasing the following message(s):
|
Withdrawing authorisation: Redundant data |
As part of the withdrawal process, the data holder MUST inform the consumer about the handling of redundant data and the right to delete. The Data Holder MAY consider using or paraphrasing the following message(s):
|
Withdrawal: Disclosure consent | As part of the disclosure consent withdrawal process, Data Recipients MUST advise the consumer to review, with the recipient that the data was disclosed to:
|
Withdrawal: Secondary User Instruction |
As part of the secondary user instruction withdrawal process, data holders MUST advise the consumer:
|
Withdrawal: Joint accounts |
As part of the process of removing a joint account approval or changing to a more restrictive disclosure option, the data holder MUST advise the consumer:
Note: The exact phrasing of the withdrawal message is at the discretion of the data holder. This standard does not affect data holders’ other notification obligations, including under rule 4A.7(3). |
Security Profile
Overview
This information security profile builds upon the foundations of the Financial-grade API Advanced Profile [FAPI-1.0-Advanced] and other standards relating to Open ID Connect 1.0 [OIDC].
For information on the specific normative references that underpin this profile refer to the Normative References section.
Symbols and Abbreviated terms
- API: Application Programming Interface
- CA: Certificate Authority
- CDR: Consumer Data Right
- CDR-SP: Consumer Data Right Security Profile
- CL: Credential Level
- DH: Data Holder
- DR: Data Recipient
- DRSP: Data Recipient Software Product
- DTA: Digital Transformation Agency
- FAPI: Financial-grade API
- FQDN: Fully Qualified Domain Name
- HoK: Holder of Key
- JSON: The JavaScript Object Notation
- JARM: JWT Secured Authorization Response Mode
- JWA: JSON Web Algorithms
- JWE: JSON Web Encryption
- JWK: JSON Web Key
- JWKS: JSON Web Key Set
- JWS: JSON Web Signing
- JWT: JSON Web Token
- IP: Identity Proofing
- LoA: Level of Assurance
- LoAs: Levels of Assurance
- MTLS: Mutually Authenticated Transport Layer Security
- OIDC: Open ID Connect
- PAR: Pushed Authorisation Requests
- PI: Personal Information
- PKCE: Proof Key for Code Exchange
- PKI: Public Key Infrastructure
- PPID: Pairwise Pseudonymous Identifier
- REST: Representational State Transfer
- SP: Data Recipient Software Product
- TDIF: Trusted Digital Identity Framework
- TLS: Transport Layer Security
CDR Federation
The CDR Federation will facilitate the secure exchange of consumer data and federation metadata between multiple system entities which will assume one or more of the following roles:
- Data Holder:
- Multiple Data Holders will be supported.
- Data Recipient:
- Multiple Data Recipients will be supported.
- Software Product:
- Multiple Software Products will be supported for each Data Recipient.
- Register:
- A register will be supported and will be maintained by the Australian Competition and Consumer Commission (ACCC) acting in its capacity as the Registrar for the CDR.
- Customer:
- The authorising customer that is authenticated by a Data Holder.
Data Holder
The Data Holder (DH) is a system entity that authenticates a Customer (resource owner or user), as part of an authorisation process initiated by a Data Recipient, and issues an authorisation for that Data Recipient to access the Customer's data via published APIs.
A Data Holder assumes the role of an [OIDC] OpenID Provider.
For the purposes of this standard a single designated organisation MAY be represented via the Register as multiple separate Data Holders to support multiple brands or market identities.
Multi-Brand Support (Separate Issuers For Data Holder Brands)
From July 4th 2022
- Where a Data Holder has multiple brands, each brand MUST have a separate issuer.
Secondary Data Holder
A Secondary Data Holder (SDH) is a system entity that is designated to provide CDR data but does so via a standard Data Holder acting as a gateway. A Secondary Data Holder does not interact directly with Data Recipients and is not registered with the Register.
A request for data from a Secondary Data Holder by a standard Data Holder is known as a Shared Responsibility Data Request.
See the Shared Responsibility section contains standards related to Secondary Data Holders and Shared Responsibility Data Requests.
Data Recipient
A Data Recipient (DR) is a system entity that is accredited to collect CDR data from Data Holders or other DRs through authorised Software Products.
A Data Recipient MUST be accredited in order to participate in the CDR Federation. Accreditation rules for Data Recipients are beyond the scope of this artefact. The process of accreditation is managed by the CDR Registrar.
For the purposes of this standard a single accredited organisation is represented via the Register as a single Data Recipient and MAY be represented by multiple separate Software Products to support multiple applications or services.
Software Product
A Data Recipient Software Product (DRSP) is a system entity that is authorised by a Data Holder to access consumer resources (APIs). A Software Product MUST capture consumer consent prior to commencing an authorisation process with a Data Holder.
A Software Product MUST be registered with the Registrar and approved for use in order to participate in the CDR Federation.
A Software Product MAY be registered for use across one or more sectors (e.g. banking and energy).
A Software Product assumes the role of an [OIDC] Relying Party (Client).
Register
The Register is a central point of discovery for both Data Holders and Data Recipients. Data Holders and Data Recipients MUST be created as entities in the Register in order for them to participate as members of the CDR Federation. The functionality of the Register will include but will not be limited to:
- Management of Identities and Access: The Register will allow registered persons, on behalf of Data Holders and Data Recipients, to manage the metadata of their associated organisations and systems.
- Management of Certificates: The Register will facilitate the issuing, management and revocation of digital certificates.
- Discoverability and Search: The Register will expose APIs and Web Interfaces in order to support metadata queries across Register entities.
Customer
For the purposes of this standard a single person or individual MAY be represented as multiple Customers according to the practice of the Data Holder according to their existing digital channels.
Authentication Flows
This profile supports the authentication flows specified by OpenID Connect [OIDC] as constrained further by [FAPI].
Specifically the OIDC Hybrid Flow outlined at section 3.3 of [OIDC].
From July 4th 2022, Authorization Code Flow outlined at section 3.1 of [OIDC] is supported.
No other flows are currently supported.
Baseline Security Provisions
Data Holders
The request_uri
parameter is only supported if the Data Holder supports PAR.
In addition, the following statements are applicable to both the OIDC Hybrid Flow and Authorization Code Flow:
- Data Holders MUST request a user identifier that can uniquely identify the customer and that is already known by the customer in the redirected page
- Data Holders MUST NOT request that the customer enter an existing password in the redirected page
- Data Holders MUST provide a one-time password (OTP) to the customer through an existing channel or mechanism that the customer can then enter into the redirected page
- The delivery mechanism for the OTP is at the discretion of the Data Holder but MUST align to existing and preferred channels for the customer and MUST NOT introduce unwarranted friction into the authentication process
- Data Holders SHOULD implement additional controls to minimise the risk of interception of the OTP through the selected delivery mechanism
- The provided OTP MUST be used only for authentication for CDR based sharing and MUST NOT be usable for the authorisation of other transactions or actions
- The provided OTP MUST be invalidated after a period of time at the discretion of the Data Holder. This expiry period SHOULD facilitate enough time for the customer to reasonably complete the authorisation process
- The provided OTP MUST be numeric digits and be between 4 and 6 digits in length
- The algorithm for the creation of the OTP is at the discretion of the Data Holder but SHOULD incorporate a level of pseudorandomness appropriate for the use case
- Data Holders SHOULD implement additional controls to minimise the risk of enumeration attacks via the redirect page
In line with CDR Rule 4.24 on restrictions when asking CDR consumers to authorise disclosure of CDR data, unwarranted friction for OTP delivery is considered to include:
- the addition of any requirements beyond normal data holder practices for verification code delivery
- providing or requesting additional information beyond normal data holder practices for verification code delivery
- offering additional or alternative services
reference or inclusion of other documents
Data Holders MUST support FAPI 1.0 Advanced Profile ([FAPI-1.0-Advanced]).
Data Holders MUST support Authorization Code Flow.
Data Holders MUST support the OIDC Hybrid Flow.
From July 10th 2023 (FAPI 1.0 Migration Phase 4),
- Data Holders MAY retire support for the OIDC Hybrid Flow.
Data Recipient Software Products
The following statements are applicable to both the OIDC Hybrid Flow and Authorization Code Flow:
Data Recipient Software Products SHOULD record the following information each time an authorisation flow is executed: username (consumer’s ID at the Data Recipient Software Product), timestamp, IP, consent scopes and duration.
Data Recipient Software Products SHOULD NOT reuse "authorization_code" values, and if reused, it will be rejected.
Data Recipient Software Products MAY send requests with a "x-fapi-customer-ip-address" header containing a valid IPv4 or IPv6 address.
Data Recipient Software Products MUST support FAPI 1.0 Advanced Profile ([FAPI-1.0-Advanced]).
Data Recipient Software Products MUST use [RFC9126] (PAR) with [PKCE] ([RFC7636]) and, if supported, MUST use S256 as the code challenge method.
Data Recipient Software Products SHOULD use Authorization Code Flow.
OIDC Hybrid Flow
The [OIDC] Hybrid Flow is a type of redirection flow where the consumer's user agent is redirected from a Data Recipient Software Product’s (Relying Party) web site to a Data Holder’s Authorisation end point in the context of an [OIDC] authentication request. The OIDC Hybrid Flow incorporates aspects of the both the implicit flow and authorisation code flow detailed under [OIDC].
Only a response_type
(see section 3.3 of [OIDC]) of code id_token
SHALL be allowed.
Authorization Code Flow
The following statements are applicable for this flow:
- Only a
response_type
(see section 3.1 of [OIDC]) ofcode
SHALL be allowed. - Data Holders MUST also support [JARM] and [PKCE]
Data Holders
Data Holders MUST support [JARM] in accordance with [FAPI-1.0-Advanced] section 5.2.2.2.
JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) Data Holders MAY support Authorisation Response encryption.
However, at present, there is no confidential information in the authorization response, hence encryption of the authorization response is not required for the purposes of security or confidentiality. In addition, whilst response encryption MAY be used, to achieve greater interoperability, it is not recommended to use encryption in this case at this time.
In addition,
- Data Holders MAY advertise they do not support authorisation response encryption: either by omitting these values from their OpenID Provider Metadata, or by presenting an empty array for the supported parameters.
- If the Data Holder supports authorisation response encryption and the
authorization_encrypted_response_alg
is omitted from the registration request, the Data Holder MAY require response encryption by returning a client registration response with the chosen “authorization_encrypted_response_alg” value.
Data Recipient Software Products
Data Recipients MUST support [JARM] in accordance with [FAPI-1.0-Advanced] section 5.2.3.2.
In addition,
- Data Recipients MUST request authorisation response signing using one of the
authorization_signing_alg_values_supported
values offered by the Data Holder. - Data Recipients MAY request response encryption using one of the advertised encryption sets.
- Data Recipients MAY request no response encryption by omitting the values in their client registration.
- If
authorization_signed_response_alg
is omitted, the default algorithm is "PS256".
Additional requirements and guidelines for the authentication flows are contained in the Consumer Experience section.
Client Authentication
This section outlines how participants in the CDR regime will authenticate clients seeking access to end points.
Note that, while [MTLS] is utilised for transaction security and as a Holder of Key mechanism, the PKI Mutual TLS OAuth Client Authentication Method SHALL NOT be supported as the mechanism for client authentication.
The following authentication methods are supported:
Data Holders SHALL authenticate the CDR Register client using one of the following Client Authentication methods:
- Self-signed JWT client assertion authenticated by the protected request endpoint according to Self-signed JWT Client Authentication, or
private_key_jwt
authentication usingclient_credentials
authorisation grant flow according to Private Key JWT Client Authentication.
- Self-signed JWT client assertion authenticated by the protected request endpoint according to Self-signed JWT Client Authentication, or
Data Holders and the CDR Register MUST authenticate Data Recipient Software Products using the Private Key JWT Client Authentication method.
Data Recipient Software Products MUST authenticate Data Holders and the CDR Register using the Self-signed JWT Client Authentication method.
Private Key JWT Client Authentication
Private Key JWT Client Authentication Non-Normative Example - CDR Register calls the Data Holder's token end point to obtain an Access Token for the purposes of calling the Data Holder's Get Metrics endpoint.
POST /token HTTP/1.1
Host: www.holder.com.au
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
client_id=5ntwEOpMdPxxy49Gt28SXWY6j3afl2CP2&
scope=admin%3Ametrics.basic%3Aread&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
## Decoded client assertion JWT
{
"alg": "PS256",
"typ": "JWT",
"kid": "12456"
}
{
"iss": "5ntwEOpMdPxxy49Gt28SXWY6j3afl2CP2",
"sub": "5ntwEOpMdPxxy49Gt28SXWY6j3aflCP2",
"iat": 1516239022,
"exp": 1516239322,
"aud": "https://www.holder.com.au/token",
"jti": "37747cd1-c105-4569-9f75-4adf28b73e31"
}
Authorisation Servers supporting private_key_jwt
Client Authentication of clients MUST support the following requirements:
- Authorisation Servers MUST support the authentication of clients using the
private_key_jwt
Client Authentication method specified at section 9 of [OIDC]. - The
private_key_jwt
authentication method is enabled through the delivery of an encoded [JWT] signed using the Data Recipient Software Product's private key and thus facilitates non-repudiation. - Client public keys are obtained from the [JWKS] endpoints.
For the client authentication assertion, the [JWT] represents an assertion that MUST contain the following REQUIRED Claim Values and MAY contain the following OPTIONAL Claim Values:
iss
- REQUIRED. Issuer Identifier for the Issuer of the response. The client ID of the bearer.sub
- REQUIRED. Subject Identifier. The client ID of the bearer.aud
- REQUIRED. Audience(s) that the JWT is intended for. The issuer identifier URL of the authorisation server according to [RFC8414] SHOULD be used as the value of the audience. In order to facilitate interoperability, the authorisation server MUST accept its Issuer Identifier, Token Endpoint URL, or the URI of the endpoint being invoked as values that identify it as an intended audience.jti
- REQUIRED. JWT ID. A unique identifier for the token, which can be used to prevent reuse of the token. These tokens MUST only be used once.exp
- REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. Value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC expiry time.iat
- OPTIONAL. Time at which the JWT was issued. Value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC issued at time.
The aforementioned assertion MUST be sent to the Authorisation Server's Token endpoint with the
POST
method and MUST include the following REQUIRED parameters, SHOULD include the following RECOMMENDED parameters and MAY contain the following OPTIONAL parameters:grant_type
- REQUIRED. The grant type(s) supported by the Authorisation Server.client_id
-- Until November 13th 2023
RECOMMENDED. The client ID of the bearer. - From November 13th 2023
OPTIONAL. The client ID of the bearer in accordance with [RFC7521].
- Until November 13th 2023
client_assertion_type
- REQUIRED. This MUST be set tourn:ietf:params:oauth:client-assertion-type:jwt-bearer
.client_assertion
- REQUIRED. The encoded assertion JWT.scope
- OPTIONAL. The requested scope as described in Section 3.3 of [RFC6749].
Self-signed JWT Client Authentication
Self-signed JWT Client Authentication Non-Normative Example - CDR Register calls the Data holder's Get Metrics end point using self-signed JWT Client Authentication (note that the “aud” claim represents the AdminBaseUri as defined in CDR Register Participant Endpoints).
GET https://admin.data.holder.com.au/cds-au/v1/admin/metrics HTTP:/1.1
Host: admin.data.holder.com.au
x-v: string
x-min-v: string
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
## Decoded Bearer token JWT
{
"alg":"PS256",
"typ":"JWT",
"kid":"12456"
}
{
"iss":"cdr-register",
"sub":"cdr-register",
"aud":"https://admin.data.holder.com.au",
"iat":1516239022,
"exp":1516239322,
"jti":"32358102-a44f-43cc-ad7c-42443d01507a"
}
Data Recipient Software Products and Data Holders supporting the self-signed JWT authentication of clients using a signed JWT MUST do so according to the following requirements:
The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following OPTIONAL Claim Values:
iss
- REQUIRED. Issuer Identifier for the Issuer of the response. The client ID of the bearer.sub
- REQUIRED. Subject Identifier. The client ID of the bearer.aud
- REQUIRED. Audience(s) that the JWT is intended for. The Data Holder or Data Recipient Software Product MUST verify that it is an intended audience for the token.Data Recipient hosted endpoints
The Resource Path for the end point being accessed SHOULD be used.
In order to facilitate interoperability and for Data Recipient Software Product hosted endpoints only, the endpoint MUST also accept the<RecipientBaseUri>
as a value identifying the intended audience.
From July 31st 2022: The Resource Path for the end point being accessed MUST be used.Data Holder Metrics endpoints
The<AdminBaseUri>
for the end point being accessed MUST be used.jti
- REQUIRED. JWT ID. A unique identifier for the token, which can be used to prevent reuse of the token. These tokens MUST only be used once.exp
- REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. Value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC expiry time.iat
- OPTIONAL. Time at which the JWT was issued. Value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC issued at time.
Validation and use of the JWT and the claims described above MUST be performed in accordance with [JWT].
The JWT MUST be accepted from the client at the requested endpoint using the "Authorization Request Header Field" mechanism as described in section 2.1 of [RFC6750].
Note: In accordance with jti
requirements, self-signed JWTs are one-time use only. The authenticating server MUST reject JWTs reuse.
CDR Register calling Data Holders
Data Holders MUST support either Private Key JWT Client Authentication or Self-signed JWT Client Authentication of the CDR Register.
Data Holders SHOULD support Private Key JWT Client Authentication but MAY support Self-signed JWT Client Authentication.
This method MAY be changed by updating Data Holder registration details with the CDR Register.
Private Key JWT authentication
If the Data Holder supports the Private Key JWT Client Authentication method for authenticating the CDR Register, it MUST also support the following requirements:
- Data Holders MUST issue a client ID that is provided to the CDR Register. The client ID is issued to the CDR Register during out of band registration processes, including, Data Holder onboarding. This MAY be a static client ID value of ‘cdr-register’.
- The authorisation grant's
grant_type
parameter MUST be set toclient_credentials
. - The authorisation grant's
scope
parameter MUST be provided and MUST be set to the scope of the resource endpoint to be accessed. - Upon successful authentication, Data Holders MUST issue an Access Token to the CDR Register. In accordance with section 4.4 of [RFC6749] an Refresh Token SHOULD NOT be included.
Self-signed JWT authentication
If the Data Holder supports the Self-signed JWT Client Authentication method for authenticating the CDR Register, the client ID MUST be set to a value of cdr-register
.
Data Holders calling Data Recipients
Non-Normative Example - Data Holder calls the Data Recipient Software Product's CDR Arrangement Revocation end point (note that the "aud" claim is "resource path" to the revocation end point).
POST https://data.recipient.com.au/arrangements/revoke HTTP/1.1
Host: data.recipient.com.au
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey …
cdr_arrangement_jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjEyNDU2In0.ey ...
## Decoded Bearer token JWT
{
"alg":"PS256",
"typ":"JWT",
"kid":"12456"
}
{
"iss":"dataholderbrand-123",
"sub":"dataholderbrand-123",
"aud":"https://data.recipient.com.au/arrangements/revoke",
"iat":1516239022,
"exp":1516239322,
"jti":"dba86502-7cf5-4719-9638-c5339a0ddb06"
}
Non-Normative Example - Data Recipient Software Product calls Data Holder's token end point. This example uses PKCE to send the code_verifier which was previously encrypted in the request object submission as the code_challenge using S256 as the code_challenge_method
POST /token HTTP/1.1
Host: www.holder.com.au
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=i1WsRn1uB1&
client_id=s6BhdRkqt3&
code_verifier=4d9213fb-d68b-49d1-a2c9-486e5a0b4e14&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
## Decoded client assertion JWT
{
"alg": "PS256",
"typ": "JWT",
"kid": "12456"
}
{
"iss": "s6BhdRkqt3",
"sub": "s6BhdRkqt3",
"iat": 1516239022,
"exp": 1516239322,
"aud": "https://www.holder.com.au/token",
"jti": "37747cd1-c105-4569-9f75-4adf28b73e31"
}
In addition to the requirements for Self-signed JWT Client Authentication, the client_id
is the Data Holder Brand ID
as issued by CDR Register.
Data Recipients calling Data Holders
In addition to the requirements for Private Key JWT Client Authentication the following requirements MUST be supported:
- The client ID represents the ID issued to the Data Recipient Software Product by the Data Holder upon successful dynamic client registration.
- The authorisation grant's
client_id
parameter value MUST represent the ID issued to the Data Recipient Software Product by the Data Holder upon successful dynamic client registration. - The authorisation grant's
grant_type
parameter value MUST only be included when invoking the Token End point and MUST be set toauthorisation_code
orclient_credentials
. The valuerefresh_token
is also valid when refreshing an access token.
Data Recipients calling the CDR Register
Non-Normative Example - Data Recipient Software Product requests CDR Register Access Token
POST /token HTTP/1.1
Host: cdr.register
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
client_id=<brand id> OR <software product id> &
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...&
scope=cdr-register%3Abank%3Aread
## Decoded client assertion JWT
{
"alg": "PS256",
"typ": "JWT",
"kid": "b50641343f8f4717a4865d238b6297b8"
}
{
"iss": "<brand id> OR <software product id>",
"sub": "<brand id> OR <software product id>",
"exp": 1516239322,
"aud": "https://cdr.register/idp/connect/token",
"jti": "37747cd1-c105-4569-9f75-4adf28b73e31"
}
## Response
{
"access_token": "eyJhbGciOiJQUz...",
"expires_in": 7200,
"token_type": "Bearer",
"scope": "cdr-register:bank:read openid"
}
In addition to the requirements for Private Key JWT Client Authentication the following requirements MUST be supported:
grant_type
MUST be set toclient_credentials
- Refresh tokens will not be provided for grant_type
client_credentials
client_id
,iss
andsub
claims MUST be set to the ID of the calling clientData Recipient Brand ID
ORSoftware Product ID
issued by the CDR Register
Client Registration
Dynamic Client Registration
Data Recipients register with Data Holders according to [DCR] to obtain client credentials used to retrieve consumer data on behalf of a consumer.
Software Statement Assertion (SSA)
As per [DCR], a Software Statement is defined in as: A digitally signed JSON Web Token (JWT) created in accordance with [JWT] that asserts metadata values about the client software
An SSA is a digitally signed JSON Web Token (JWT) created in accordance with [JWT] that asserts metadata values about the client software.
Such that:
- The CDR Register MUST issue Software Statements to active Data Recipients for active Software Products
- The CDR Register MUST issue distinct Software Statements for each
Software Product ID
- Software Statements are issued with a 10 minute expiry time
- As per [FAPI-1.0-Advanced], SSAs are signed by the CDR Register using PS256
- CDR Register public keys are exposed on a dedicated JWKS URI endpoint
- The CDR Register JWKS endpoint is an unauthenticated endpoint, using TLS
- Data Recipients MUST present a valid SSA when undertaking dynamic client registration
- Data Holders MUST NOT register Data Recipient software products unless they present a verified Registration Request with a verified SSA
Refer to the Register APIs section for the endpoint definitions that will be used to retrieve and validate SSAs.
SSA Definition
Example SSA:
eyJhbGciOiJQUzI1NiIsImtpZCI6ImI4ZmFjZjJmZjM5NDQ0Zjc4MWUwYmU1ZGI0YjE0ZjE2IiwidHlwIjoiSldUIn0.eyJpc3MiOiJjZHItcmVnaXN0ZXIiLCJpYXQiOjE1NzE4MDgxMTEsImV4cCI6MjE0NzQ4MzY0NiwianRpIjoiM2JjMjA1YTFlYmM5NDNmYmI2MjRiMTRmY2IyNDExOTYiLCJjbGllbnRfbmFtZSI6Ik1vY2sgU29mdHdhcmUiLCJjbGllbnRfZGVzY3JpcHRpb24iOiJBIG1vY2sgc29mdHdhcmUgcHJvZHVjdCIsImNsaWVudF91cmkiOiJodHRwczovL3d3dy5tb2NrY29tcGFueS5jb20uYXUiLCJsZWdhbF9lbnRpdHlfaWQiOiIzQjBCMEE3Qi0zRTdCLTRBMkMtOTQ5Ny1FMzU3QTcxRDA3QzciLCJsZWdhbF9lbnRpdHlfbmFtZSI6Ik1vY2sgQ29tcGFueSBQdHkgTHRkLiIsIm9yZ19pZCI6IjNCMEIwQTdCLTNFN0ItNEEyQy05NDk3LUUzNTdBNzFEMDdDOCIsIm9yZ19uYW1lIjoiTW9jayBDb21wYW55IEJyYW5kIiwicmVkaXJlY3RfdXJpcyI6WyJodHRwczovL3d3dy5tb2NrY29tcGFueS5jb20uYXUvcmVkaXJlY3RzL3JlZGlyZWN0MSIsImh0dHBzOi8vd3d3Lm1vY2tjb21wYW55LmNvbS5hdS9yZWRpcmVjdHMvcmVkaXJlY3QyIl0sInNlY3Rvcl9pZGVudGlmaWVyX3VyaSI6Imh0dHBzOi8vd3d3Lm1vY2tjb21wYW55LmNvbS5hdS9zZWN0b3JfaWRlbnRpZmllci5qc29uIiwibG9nb191cmkiOiJodHRwczovL3d3dy5tb2NrY29tcGFueS5jb20uYXUvbG9nb3MvbG9nbzEucG5nIiwidG9zX3VyaSI6Imh0dHBzOi8vd3d3Lm1vY2tjb21wYW55LmNvbS5hdS90b3MuaHRtbCIsInBvbGljeV91cmkiOiJodHRwczovL3d3dy5tb2NrY29tcGFueS5jb20uYXUvcG9saWN5Lmh0bWwiLCJqd2tzX3VyaSI6Imh0dHBzOi8vd3d3Lm1vY2tjb21wYW55LmNvbS5hdS9qd2tzIiwicmV2b2NhdGlvbl91cmkiOiJodHRwczovL3d3dy5tb2NrY29tcGFueS5jb20uYXUvcmV2b2NhdGlvbiIsInJlY2lwaWVudF9iYXNlX3VyaSI6Imh0dHBzOi8vd3d3Lm1vY2tjb21wYW55LmNvbS5hdSIsInNvZnR3YXJlX2lkIjoiNzQwQzM2OEYtRUNGOS00RDI5LUEyRUEtMDUxNEE2NkIwQ0RFIiwic29mdHdhcmVfcm9sZXMiOiJkYXRhLXJlY2lwaWVudC1zb2Z0d2FyZS1wcm9kdWN0Iiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBiYW5rOmFjY291bnRzLmJhc2ljOnJlYWQgYmFuazphY2NvdW50cy5kZXRhaWw6cmVhZCBiYW5rOnRyYW5zYWN0aW9uczpyZWFkIGJhbms6cGF5ZWVzOnJlYWQgYmFuazpyZWd1bGFyX3BheW1lbnRzOnJlYWQgZW5lcmd5OmVsZWN0cmljaXR5LnNlcnZpY2Vwb2ludHMuYmFzaWM6cmVhZCBlbmVyZ3k6ZWxlY3RyaWNpdHkuc2VydmljZXBvaW50cy5kZXRhaWw6cmVhZCBlbmVyZ3k6ZWxlY3RyaWNpdHkudXNhZ2U6cmVhZCBlbmVyZ3k6ZWxlY3RyaWNpdHkuZGVyOnJlYWQgZW5lcmd5OmFjY291bnRzLmJhc2ljOnJlYWQgZW5lcmd5OmFjY291bnRzLmRldGFpbDpyZWFkIGVuZXJneTphY2NvdW50cy5wYXltZW50c2NoZWR1bGU6cmVhZCBlbmVyZ3k6YWNjb3VudHMuY29uY2Vzc2lvbnM6cmVhZCBlbmVyZ3k6YmlsbGluZzpyZWFkIGNvbW1vbjpjdXN0b21lci5iYXNpYzpyZWFkIGNvbW1vbjpjdXN0b21lci5kZXRhaWw6cmVhZCBjZHI6cmVnaXN0cmF0aW9uIn0.XTSst96xOifAnaMaBj0I5nO5vbtNwvz304hJ9I_jPOcdD6vitmLiyWdkdW5GKA4JAa62_DmRIU_3zXQL0gSSJxoWhCSbuIlfwDtXFpFZzQAnTv-hOul-5clYmXvQqqEqWvbZZ4g7IKdWdROp4fzWFXB0VKf-_qzue_Kksy3A9CwdZRmNMDFtIApkSULqxK3S8D2nFa3lvGzegl76Ji7p0Zjkyu8YexFyKCahTEGzQrRQeVILpaN107XHNlSWlhsv4hr1PXwG2Pn1z54SCG9tVOZ10WaqZ5SMjRqsQN-lVYSVe5BCTpQ-N_GnYuUeWh0rOJ9CrA8CUN_twCJXyW3I5w
Associated JWKS:
{
"keys": [
{
"kid": "b8facf2ff39444f781e0be5db4b14f16",
"kty": "RSA",
"key_ops": [
"sign",
"verify"
],
"n": "s0zGoaOEJE8HDfHjWtO0xLXtuPcwio8BEoj0-uu9kxxDIF7jH0jb06EwoPkb83BET59x6C0TtRfc_I5ZDksQKRClWXzbazqi62M5YhCgwyB-S09PJb8P1GfQBYyK346nLKARHbFJ1t1SHARcVFJA_8NeHfQn_0fyEc55R3GGNDL3YQtjEoTb-LMR-KpcPB2BpyDuie-jk-3f1t0EfvnkVp-6co1_KTXrbwuYtH31YBZLgU4JeZEJLTnGdMKmJppZ9SnyrBB461hMmw0HJHJj6uZJSiP2onmvlrUezv1T3NM3HOE7WHxlps9MUJj3vcpea-O6n5JBX8emTduLuLuKuw",
"e": "AQAB"
}
]
}
Decoded SSA
{
"alg": "PS256",
"kid": "b8facf2ff39444f781e0be5db4b14f16",
"typ": "JWT"
}
{
"iss": "cdr-register",
"iat": 1571808111,
"exp": 2147483646,
"jti": "3bc205a1ebc943fbb624b14fcb241196",
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read energy:electricity.servicepoints.basic:read energy:electricity.servicepoints.detail:read energy:electricity.usage:read energy:electricity.der:read energy:accounts.basic:read energy:accounts.detail:read energy:accounts.paymentschedule:read energy:accounts.concessions:read energy:billing:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
The SSA will conform to the requirements of [DCR] with the following clarifications:
Client Metadata | Required | Modifiable | Description |
---|---|---|---|
iss | Required | Contains the iss (issuer) claim denoting the party attesting to the claims in the software statementvalue: "cdr-register" |
|
iat | Required | The time at which the request was issued by the CDR Register, expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC | |
exp | Required | The time at which the SSA expires expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC | |
jti | Required | Unique identifier for the JWT, used to prevent reuse of the SSA. | |
legal_entity_id | Optional | A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Legal Entity | |
legal_entity_name | Optional | Human-readable string name of the Accredited Data Recipient Legal Entity | |
org_id | Required | A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Brand | |
org_name | Required | Human-readable string name of the Accredited Data Recipient Brand to be presented to the end user during authorization | |
client_name | Required | Human-readable string name of the software product to be presented to the end-user during authorization | |
client_description | Required | Human-readable string name of the software product description to be presented to the end user during authorization | |
client_uri | Required | URL string of a web page providing information about the client | |
redirect_uris | Required | Array of redirection URI strings for use in redirect-based flows | |
sector_identifier_uri | Optional | URL string referencing the client's sector identifier URI, used as an optional input to the Pairwise Identifier as described in described in section 8 of [OIDC] | |
logo_uri | Required | URL string that references a logo for the client software product. The server SHOULD display this image to the end-user during approval | |
tos_uri | Optional | URL string that points to a human-readable terms of service document for the Software Product | |
policy_uri | Optional | URL string that points to a human-readable policy document for the Software Product | |
jwks_uri | Required | URL string referencing the client's JSON Web Key (JWK) Set [RFC7517] document, which contains the client's public keys | |
revocation_uri | Required | URI string that references the location of the Software Product consent revocation endpoint as per Consumer Data Standards Endpoints | |
recipient_base_uri | Required | Base URI for the Consumer Data Standard Data Recipient endpoints. This SHOULD be the base to provide reference to all other Data Recipient Endpoints | |
software_id | Required | String representing a unique identifier assigned by the Register and used by registration endpoints to identify the software product to be dynamically registered. The software_id will remain the same across multiple updates or versions of the same piece of software.The software_id SHOULD be used as the primary external identifier for the client to prevent duplicate client registrations |
|
software_roles | Required | String containing a role of the software in the CDR Regime. Initially the only value used will be “data-recipient-software-product” | |
scope | Required | String containing a space-separated list of scope values that the client can use when requesting access tokens. These CDS scope values are defined at: Authorisation ScopesThe DCR scope value is defined at: Client Registration ManagementAs per the CDS Scopes and Claims, openid and profile are included in the SSA |
Get Software Statement Assertion API v1 & v2 has the scope claim explicitly defined.
Registration Request using JWT
Example Request Client registration with OpenID Hybrid Flow
HTTP/1.1 POST /register
Content-Type: application/jwt
Accept: application/json
### Non-normative Decoded JWT
{
"alg":"PS256",
"typ":"JWT",
"kid":"12456"
}
{
"iss": "CDR Software Product ID",
"iat": 1571908322,
"exp": 2148483456,
"jti": "37747cd1c10545699f754adf28b73e31",
"aud": "https://secure.api.dataholder.com/issuer",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code id_token"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"id_token_encrypted_response_alg": "RSA-OAEP",
"id_token_encrypted_response_enc": "A256GCM",
"request_object_signing_alg": "PS256",
"software_statement": "string"
}
{
"signature":...
}
Example Request This example creates a FAPI 1.0 Phase 3 client registration that uses Authorization Code Flow with JARM encryption
HTTP/1.1 POST /register
Content-Type: application/jwt
Accept: application/json
### Non-normative Decoded JWT
{
"alg":"PS256",
"typ":"JWT",
"kid":"12456"
}
{
"iss": "CDR Software Product ID",
"iat": 1571908322,
"exp": 2148483456,
"jti": "37747cd1c10545699f754adf28b73e31",
"aud": "https://secure.api.dataholder.com/issuer",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"authorization_signed_response_alg": "PS256",
"authorization_encrypted_response_alg": "RSA-OAEP",
"authorization_encrypted_response_enc": "A128CBC-HS256",
"request_object_signing_alg": "PS256",
"software_statement": "string"
}{
"signature":...
}
To register with a Data Holder, the Data Recipient sends an HTTP POST to the Data Holder registration endpoint.
- The request MUST be presented in the format of a [RFC7519] compliant JWT.
- The request MUST use the HTTP POST method, using the
application/jwt
content type. - The JWT MUST be signed using algorithms specified in section 8.6 of [FAPI-1.0-Advanced]
The client registration request MUST contain the following claims in the JWT payload unless designated as Optional:
Claim | Required | Description |
---|---|---|
iss | Required | Contains the identifier for the Data Recipient Software Product (SoftwareProductId) as defined in the CDR Register |
iat | Required | The time at which the request was issued by the Data Recipient expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC |
exp | Required | The time at which the request expires expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC |
jti | Required | Unique identifier for the JWT, used to prevent reuse of the token. |
aud | Required | Contains the DH issuer value as described in the OIDC Discovery Document |
redirect_uris | Optional | Array of redirection URI strings for use in redirect-based flows. If used, redirect_uris MUST match or be a subset of the redirect_uris as defined in the SSA |
token_endpoint_auth_method | Required | The requested authentication method for the token endpoint. The only supported method will be private_key_jwt |
token_endpoint_auth_signing_alg | Required | The algorithm used for signing the JWT |
grant_types | Required | Array of OAuth 2.0 grant type strings that the client can use at the token endpoint. Supported values: [client_credentials, authorization_code, refresh_token] |
response_types | Required | Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint. values: ["code", "code id_token"] Response type value “code” is required for Authorization Code Flow. Response type value “code id_token” is required for OIDC Hybrid Flow. |
application_type | Optional | Kind of the application. The only supported application type will be web |
id_token_signed_response_alg | Required | Algorithm with which an id_token is to be signedSupported values as constrained by [FAPI-1.0-Advanced]. Required for both Authorization Code Flow (response_type “code”) and OIDC Hybrid Flow (response_type “code id_token”). |
id_token_encrypted_response_alg | Conditional | JWE alg algorithm with which an id_token is to be encrypted.Required if OIDC Hybrid Flow (response type code id_token ) is registered. |
id_token_encrypted_response_enc | Conditional | JWE enc algorithm with which an id_token is to be encrypted.Required if OIDC Hybrid Flow (response type code id_token ) is registered. |
authorization_signed_response_alg | Conditional | The JWS alg algorithm required for signing authorization responses. If this is specified, the response will be signed using JWS and the configured algorithm. The algorithm “none” is not allowed. Required if response_type of “code” is registered by the client. |
authorization_encrypted_response_alg | Conditional | The JWE alg algorithm required for encrypting authorization responses. If unspecified, the default is that no encryption is performed. Required if “authorization_encrypted_response_enc” is included. |
authorization_encrypted_response_enc | Optional | The JWE enc algorithm required for encrypting authorization responses. If “authorization_encrypted_response_alg” is specified, the default for this value is “A128CBC-HS256”. |
request_object_signing_alg | Optional | Algorithm which the ADR expects to sign the request object if a request object will be part of the authorization request sent to the Data HolderIf field not present in the request, data holders are expected to respond with an appropriate default valueSupported values as constrained by [FAPI-1.0-Advanced] |
software_statement | Required | Software statement assertion issued by the CDR Register |
ID Token Algorithm Selection Considerations
When requiring ID Token encryption, the following requirements are applicable.
Participants MUST support, at a minimum, the following ID Token algorithms:
Claim | Values |
---|---|
id_token_encrypted_response_alg | RSA-OAEPRSA-OAEP-256 |
id_token_encrypted_response_enc | A256GCMA128CBC-HS256 |
Data Holders MUST support at a minimum, 1 algorithm for each claim.
Data Recipients MUST support all the algorithms used in the ecosystem to ensure they can communicate with all Data Holders.
ID Token algorithm considerations remain relevant where the OIDC Hybrid Flow is leveraged as defined in the Consumer Data Standards and in accordance with sections 5.1.1, 5.2.2.1, and 5.2.3.1 of [FAPI-1.0-Advanced].
JARM Response Encryption Considerations
If Data Holders support authorisation response encryption, they MUST support, at a minimum, one of each of the following alg
and enc
algorithms:
Claim | Values |
---|---|
authorization_encryption_alg_values_supported | RSA-OAEP RSA-OAEP-256 |
authorization_encryption_enc_values_supported | A256GCM A128CBC-HS256 |
Data Recipients MUST support the minimum required algorithms.
Registration Validation
Validation and use of the JWT and the claims described above MUST be performed in accordance with [JWT].
SSA JWT signatures MUST be verified against the associated JWK published at the CDR Register JWKS endpoint.
The registration request JWT MUST be verified against the associated JWK published by the Data Recipient. Data Holders are required to verify the request JWT signature against an associated JWK from the jwks_uri
extracted from the SSA.
Data Holders MUST NOT allow multiple active registrations for the same software_id
.
From 31st August 2022, Data Holders MUST ignore unsupported authorisation scopes presented in the SSA for the creation and update of client registrations.
Data Holders MUST adhere to the NFR performance requirements when validating and responding to registration requests. Additional validation processes (such as outbound white-listing of data recipient endpoints) MUST NOT prevent specified response times being met.
Registration Response
Example Created Response OIDC Hybrid Flow
HTTP/1.1 201 Created
Content-Type: application/json
{
"client_id": "2cfefa98-7d4a-4bcb-95da-47063b84d410",
"client_id_issued_at": 1574398833,
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code id_token"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"id_token_encrypted_response_alg": "RSA-OAEP",
"id_token_encrypted_response_enc": "A256GCM",
"request_object_signing_alg": "PS256",
"software_statement": "string",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
Example Created Response Authorization Code Flow This example creates a FAPI 1.0 Phase 3 client registration that uses Authorization Code Flow with JARM encryption
HTTP/1.1 201 Created
Content-Type: application/json
{
"client_id": "2cfefa98-7d4a-4bcb-95da-47063b84d410",
"client_id_issued_at": 1574398833,
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"authorization_signed_response_alg": "PS256",
"authorization_encrypted_response_alg": "RSA-OAEP",
"authorization_encrypted_response_enc": "A128CBC-HS256",
"request_object_signing_alg": "PS256",
"software_statement": "string",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
On successful registration, the response MUST be returned to the Data Recipient conforming to Section 3.2.1 of [DCR].
Claim | Required | Description |
---|---|---|
client_id | Required | Contains the dynamically generated identifier for the Software Product issued by the Data Holder |
client_id_issued_at | Optional | Time at which the client identifier was issued |
As per Section 3.2.1 of [DCR], additionally, the authorisation server MUST return all registered metadata about this client, including any fields provisioned by the authorisation server itself.
The Software Statement value MUST be returned unmodified. Client metadata elements used from the software statement MUST also be returned directly as top-level client metadata values in the registration response.
Any additional claims MUST be ignored and not returned on completion of the request.
Registration Errors
Example Error Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_software_statement",
"error_description": "Duplicate registrations for a given software_id are not valid"
}
When an error condition occurs during a registration request, the response MUST be returned to the Accredited Data Recipient conforming to Section 3.2.2 of [DCR].
Duplicate registrations are not permitted so attempts to create a registration which already exists MUST return an HTTP 400 error.
Registration error responses schemas are defined in the DCR APIs section.
For those Registration errors which do not map to Section 3.2.2 of [DCR], HTTP Response Codes in the Consumer Data Standards SHOULD be used.
Registration Management
Non-Normative Example for access token retrieval to perform registration management
HTTP/1.1 POST /token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
scope=cdr%3Aregistration&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
### Decoded client assertion JWT
{
"alg": "PS256",
"typ": "JWT",
"kid": "12456"
}
{
"iss": "12345",
"sub": "12345",
"iat": 1516239022,
"exp": 1516239322,
"aud": "https://www.holder.com.au/token",
"jti": "37747cd1-c105-4569-9f75-4adf28b73e31"
}
Data Holders MUST expose Client Registration Management endpoints as defined in the DCR APIs
HTTP Verb | MTLS | HoK | Client Authentication | |
---|---|---|---|---|
POST /register | Required | N/A | ||
GET /register/{clientID} | Required | Client Credentials with cdr:registration scope | ||
PUT /register/{clientID} | Required | Client Credentials with cdr:registration scope | ||
DELETE /register/{clientID} | Optional | Client Credentials with cdr:registration scope |
- Registration endpoints will be exposed in the OIDC Discovery Configuration Endpoint
- POST and PUT operations MUST accept the SSA payload.
- Fields data holders do not support are not persisted.
- Access tokens issued for consuming CDR Data SHOULD NOT be used for client registration maintenance and vice-versa
PUT Operations
Registrations MUST only be updated via Registration PUT operations
PUT operations are to be used for one of two scenarios:
- The client has updated their registration details on the CDR Register and updates this information to the data holder
- A new version of the SSA has been released and the client updates this information to the data holder
Participant Statuses
Data Recipient and Software Product Statuses
The accreditation status of Data Recipients, and the status of their associated Software Products, MAY traverse through multiple statuses in the CDR.
The status of participants is maintained in the CDR Register by the CDR Registrar according to determination of the CDR Accreditor or the participant themselves.
CDR data MAY only be disclosed to active Data Recipients. Data Holders MUST cease disclosing CDR data where the accreditation of a Data Recipient or Software Package is:
- Suspended or revoked by the CDR Registrar.
- Surrendered by the Data Recipient.
The CDR Register MUST notify all Data Holders of the above changes in Data Recipient and Software Package status via the Register APIs.
The CDR Register MUST expose the statuses of data recipients and their associated software products via the Register APIs, using the following state models:
Data Recipient Status
Software Product Status
Status Mapping
When the CDR Registrar changes the accreditation status for a Data Recipient for any status other than active, the associated Software Product statuses MUST be changed accordingly.
The cascading status mappings are as follows:
Data Recipient Status | Cascaded Software Product Status |
---|---|
Suspended | Inactive |
Revoked | Removed |
Surrendered | Removed |
Archiving
Dormant entries will be identified and archived automatically within the CDR Register.
Dormant entries are defined as those records that have reached and maintained an end state in the CDR Register for the past 2 years.
The table below outlines the end state for each Register entry type:
Register Entity | End State |
---|---|
Data Holder | Removed |
Data Holder Brand | Removed |
Data Recipient | Surrendered, Revoked |
Data Recipient Brand | Removed |
Data Recipient Software Product | Removed |
Data Holder Responsibilities
The CDR Registrar has the ability to change the status of a Software Product independently of the Data Recipient's accreditation status. Therefore, both the Data Recipient and Software Product statuses SHOULD be referenced, to determine the Data Holder's responsibilities for data disclosure, consent and registration management.
Data Recipient Status |
Software Product Status |
Disclose of CDR Data | Facilitate Consent Authorisation | Facilitate Consent Withdrawal | Invalidate Consents | Cleanup Registration |
---|---|---|---|---|---|---|
Active | Active | |||||
Active | Inactive | |||||
Active | Removed | |||||
Suspended | Inactive | |||||
Suspended | Removed | |||||
Revoked | Removed | |||||
Surrendered | Removed |
- Disclosure of CDR data MUST be in response to valid requests in accordance with the CDR rules and standards
- The status of a Data Recipient Brand does not impact Data Holder responsibilities due to the cascade rules outlined above
- When a Data Recipient status is Suspended, Revoked or Surrendered the Software Product status cannot be Active
- Invalidation of consents and cleanup of registrations are bulk operations. It is reasonable to execute these as batch tasks performed overnight
- The CDR Register MUST NOT provide an undefined status for Data Recipient or Data Recipient Software Product Statuses
- If Data Holders do not receive a status for a Data Recipient or Data Recipient Software Product, or receives a status that is not recognised, Data Holders SHOULD ignore the value and use the previous status value retrieved from the CDR Register. Data Holders SHOULD continue to use the previous status value until a valid value is returned by the CDR Register or the ACCC informs the Data Holder using an alternative mechanism. There is no upper bound for how long previous status values should remain trusted.
Metadata Cache Management
Data Holders MUST react to Data Recipient and associated Software Statuses changes within 5 minutes of the change occurring on the CDR Register.
To achieve this, Data Holders will poll the Get Data Recipients Statuses, Get Software Products Statuses and Get Data Recipients APIs to retrieve the current statuses and cache these for use during requests for Consumer Data.
Data Holders MUST choose a frequency of polling which ensures their systems can respond to status changes within the required timeframe.
Data Holders and Data Recipients MUST cache all other participant data they use and periodically update this cache using a slow poll. This ensures that changes to participant configuration propagates throughout the ecosystem in a predictable timeframe.
The CDR Register MAY cache the responses for public APIs hosted by the CDR Register. If caching is supported the CDR Register MUST support ETag cache validators allowing participants to detect whether the content has changed.
Cache update periods
The following are the recommended caching times for data retrieved from the Register APIs.
API | Type | Period |
---|---|---|
GetDataRecipientsStatus | Public | 2-5 minutes |
GetSoftwareProductsStatus | Public | 2-5 minutes |
GetDataRecipients (statuses) | Public | 2-5 minutes |
GetDataRecipients (other data) | Public | 6 hours |
GetDataHolderBrands | Private | 6 hours |
OIDC Client Types
Only Confidential Clients SHALL be supported under this profile. Therefore, Public clients SHALL NOT be supported.
In reference to the client types referenced in section 2.1 of [OAUTH2]:
- Confidential Clients MUST be supported under this profile.
- Public clients MUST NOT be supported.
JSON Web Key Sets
Data Holder public keys MUST only be obtained from the standard OIDC end point used for that purpose.
Data Recipient Software Product public keys MUST only be obtained from the URI registered with the CDR Register.
CDR Register public keys MUST only be obtained from the end point exposed for that purpose.
Consent
Consent requirements will be communicated between the Data Recipient Software Product and Data Holder via the authorisation request object. The primary mechanism for capturing consent will be scopes and claims under [OIDC].
Other patterns for the establishment of consent MAY be considered in the future, including the incorporation of fine-grained consent for specific use cases.
Scopes and Claims
OIDC Scopes
In addition to CDR data scopes the following scopes MUST be supported:
openid
: As described as section 3.1.2.1 of [OIDC], this scope MUST be present on each authentication request.profile
: Data Holders MUST support theprofile
scope as described in section 5.4 of [OIDC]. This scope MAY be present on an authentication request.
Claims
The following normal [OIDC] and standard claims claims MUST be supported for the authenticated End-User*:
sub
: Pairwise Pseudonymous Identifier (PPID) for the End-User at the Data Holder.acr
: Authentication Context Class Reference. MUST contain a valid ordinal LoA value.auth_time
: Time when the End-User authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTCauth_time
. It MUST be returned by the Data Holder in the ID Token when the Data Recipient Software Product has requested it as an essential claim according to section 2 of the [OIDC] standard. It SHOULD NOT be returned via the UserInfo endpoint.name
: End-User's full name in displayable form including all name parts.given_name
: Given name(s) or first name(s) of the End-User.family_name
: Surname(s) or last name(s) of the End-User.updated_at
: Time the End-User's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTCupdated_at
time.
The following additional claims MUST be supported:
refresh_token_expires_at
: indicates the date-time at which the most recently provided refresh token will expire. Its value MUST be a number containing a NumericDate value, as specified in section 2 of section 2 [JWT]. If no refresh token has been provided then a zero value should be returned.sharing_expires_at
: indicates the date-time at which the current sharing arrangement will expire. Its value MUST be a number containing a NumericDate value, as specified in section 2 of [JWT]. If consent is not complete or asharing_duration
was not requested in the authorisation request object then a zero value should be returned.
The following standard [OIDC] claims MAY be supported:
email
: End-User's preferred e-mail address. Its value MUST conform to the [RFC5322] addr-spec syntax. The Data Recipient MUST NOT rely upon this value being unique, as discussed in Section 5.7 of [OIDC].email_verified
: True if the End-User's e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the Data Holder took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating.phone_number
: End-User's preferred telephone number. [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.phone_number_verified
: True if the End-User's phone number has been verified; otherwise false. When this Claim Value is true, this means that the Data Holder took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed. The means by which a phone number is verified is context- specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. When true, the phone_number Claim MUST be in [E.164] format and any extensions MUST be represented in [RFC3966] format.address
: End-User's preferred postal address. The value of the address member is a JSON [RFC4627] structure containing some or all of the members defined in Section 5.1.1.
Other [OIDC] Standard Claims MUST be ignored and not authorised.
Note: For non-individual consumers, claims available via the profile scope will only return the details of the authenticated End-User and not the organisation or non-individual consumer. Data Holders SHOULD explicitly capture Claims requested by the Data Recipient. If the data cluster or [OIDC] profile scope changes meaning in future this ensures the Data Holder only returns what the consumer initially authorised to disclose.
Tokens
ID Token
Non-Normative Example - acr
{
"iss": "https://www.holder.com.au",
"sub": "a9ebbef6-1f0b-44eb-96cf-0c5b51b37ab2",
"aud": "12345",
"nonce": "n-0S6_WzA2Mj",
"exp": 1311281970,
"iat": 1311280970,
"nbf": 1311280970,
"auth_time": 1311280969,
"acr": "urn:cds.au:cdr:3",
"refresh_token_expires_at": 1311281970,
"sharing_expires_at": 1311281970
}
Non-Normative Example - FAPI 1.0 Final Phase 3 Obligations
{
"iss": "https://www.holder.com.au",
"sub": "a9ebbef6-1f0b-44eb-96cf-0c5b51b37ab2",
"aud": "12345",
"nonce": "n-0S6_WzA2Mj",
"exp": 1311281970,
"iat": 1311280970,
"nbf": 1311280970,
"auth_time": 1311280969,
"acr": "urn:cds.au:cdr:2"
}
ID Tokens are specified in section 2 of the [OIDC] standard.
Baseline ID Token requirements
In addition to the mandatory claims specified in section 2 of the [OIDC] standard, required claims for ID Tokens as part of Hybrid Flow authentication MUST align to section 3.3 (Authentication using the Hybrid Flow) of the [OIDC] standards and section 5.2.2 and section 8.4.3 of the [FAPI-1.0-Advanced] profile.
ID Tokens MUST be signed by Data Holders as specified in section 8.6 of [FAPI-1.0-Advanced].
OIDC Hybrid Flow requirements
In accordance with [FAPI-1.0-Advanced], ID Tokens MUST be signed and encrypted when returned to a Data Recipient Software Product from both the Authorisation End Point and Token End Point.
The ID Token returned from the Authorisation End Point MUST NOT contain any Personal Information (PI) claims.
Hashing value for state and authorisation code
The following requirements apply to the OIDC Hybrid Flow:
- The
c_hash
value MUST be generated according to section 3.3.2.11 of [OIDC]. - The
s_hash
value MUST be generated according to section 5.1.1 of [FAPI-1.0-Advanced].
Authorization Code Flow requirements
For response_type
code
, in accordance with [FAPI-1.0-Advanced], ID Tokens MUST be signed when returned to a Data Recipient Software Product from the Token End Point.
Access Token
Access Tokens MUST be used as specified in section 10.3 of [OAUTH2].
An Access Token MUST expire between 2 minutes to 10 minutes after the Data Holder issues it (at the discretion of the Data Holder).
The process for refreshing an Access Token is described in section 12.1 of [OIDC].
- Data Holders MUST reject token request with an authorization code (Section 1.3.1 of [RFC6749]) if it has been previously used
Refresh Token
Refresh Tokens MUST be supported by Data Holders.
The usage of Refresh Tokens is specified in section 12 of [OIDC].
The expiration time for a Refresh Token MUST be set by the Data Holder.
Refresh Token expiration MAY be any length of time greater than 28 days but MUST NOT exceed the end of the duration of sharing consented to by the Consumer.
- Data Holders MUST NOT cycle refresh tokens (rotation). In other words, Refresh Tokens SHOULD be issued with an "exp" equal to the sharing duration authorised by the Customer.
Token Expiry
The expiry time for issued access tokens and refresh tokens MUST be deterministic for the Data Recipient Software Product.
In order to achieve this:
- The Data Holder MUST indicate the lifetime in seconds of the access token in the
expires_in
field of the JSON object returned by the token end-point (see section 4.2.2 of [OAUTH2]).
Identifiers and Subject Types
sub claim
The identifier for an authenticated end-user (subject) MUST be passed in the sub
claim of an ID Token and UserInfo response as defined by [OIDC].
The Data Holder MUST generate the sub
value as a Pairwise Pseudonymous Identifier (PPID) as described in section 8 of [OIDC]. Furthermore, the identifier MUST be unique per customer as per the definition of customer in the CDR Federation section of this profile.
The Data Holder MUST support the sector_identifier_uri
in PPID generation according to [OIDC] if this field was supplied by the client during registration.
It is RECOMMENDED that the sub
value is generated as a version 4 Universally Unique
Identifier (UUID) [RFC4122].
CDR Arrangement ID
Non-normative example: Token Endpoint hydration
Request
POST /token HTTP/1.1
Host: https://data.holder.com.au
Content-Type: application/x-www-form-urlencoded
client_id=s6BhdRkqt3
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
&grant_type=refresh_token
&refresh_token=8xLOxBtZp8
&scope=openid%20profile
Response
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"expires_in": 3600,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
"id_token": "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUl...",
"cdr_arrangement_id": "02e7c9d9-cfe7-4c3e-8f64-e91173c84ecb"
}
Decoded JWT
{
"iss": "https://data.holder.com.au",
"sub": "a9ebbef6-1f0b-44eb-96cf-0c5b51b37ab2",
"aud": "12345",
"nonce": "n-0S6_WzA2Mj",
"exp": 1311281970,
"iat": 1311280970,
"nbf": 1311280970,
"auth_time": 1311280969,
"acr": "urn:cds.au:cdr:3",
"refresh_token_expires_at": 1311281970,
"sharing_expires_at": 1311281970
}
Decoded JWT - FAPI 1.0 Final Phase 3 Obligation
{
"iss": "https://data.holder.com.au",
"sub": "a9ebbef6-1f0b-44eb-96cf-0c5b51b37ab2",
"aud": "12345",
"nonce": "n-0S6_WzA2Mj",
"exp": 1311281970,
"iat": 1311280970,
"nbf": 1311280970,
"auth_time": 1311280969,
"acr": "urn:cds.au:cdr:3"
}
Non-normative example: Token Introspection Endpoint hydration
Request
POST /token/introspect HTTP/1.1
Host: https://data.holder.com.au
Content-Type: application/x-www-form-urlencoded
client_id=s6BhdRkqt3
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
&token=tGzv3JOkF0XG5Qx2TlKWIA
&token_type_hint=refresh_token
Response
{
"active": true,
"exp": 1311281970,
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read",
"cdr_arrangement_id": "02e7c9d9-cfe7-4c3e-8f64-e91173c84ecb"
}
The CDR Arrangement ID is a unique string representing a consent arrangement between a Data Recipient Software Product and Data Holder for a given consumer.
The identifier MUST be unique per customer according to the definition of customer in the CDR Federation section of this profile.
The Data Holder MUST provide the CDR Arrangement ID as the claim cdr_arrangement_id
in the Token End Point response and Token Introspection End Point response.
A Data Holder MUST only return the cdr_arrangement_id
in the Token and Token Introspection End Point responses if they also support concurrent consent. This ensures that Data Recipient Software Products have a reliable way to determine whether a given Data Holder supports concurrent consent.
Statements related to the CDR Arrangement ID:
- The CDR Arrangement ID MUST be unique to a Data Holder
- The CDR Arrangement ID MUST be non-guessable and MUST NOT identify a consumer
- A CDR Arrangement ID SHOULD be generated using an algorithm that reduces the chances of collision
- A CDR Arrangement ID MUST be static across consents within the one sharing arrangement (e.g. across consent renewal and re-authorisation)
Obtaining a CDR Arrangement ID
For any existing consents, Data Holders MUST retrospectively generate a cdr_arrangement_id
such that Data Recipient Software Products can obtain a valid cdr_arrangement_id
for all active consents they hold.
A Data Recipient Software Product can call either the Token or Token Introspection End Points at any point post-consent to obtain the CDR Arrangement ID in the response JSON as the claim cdr_arrangement_id
.
Levels of Assurance (LoAs)
Levels Of Assurance (LoAs), returned after a successful authentication MUST be represented in Single Ordinal form where a single LoA value is represented.
Single Ordinal
A Single LoA value is carried in the acr
claim which is described in section 2 of [OIDC].
An LoA of 2 is represented by the URI:
urn:cds.au:cdr:2
- The authenticator used to attain this level MUST conform with the Credential Level
CL1
rules specified under the Trusted Digital Identity Framework [TDIF] Authentication Credential Requirements specification.
- The authenticator used to attain this level MUST conform with the Credential Level
An LoA of 3 is represented by the URI:
urn:cds.au:cdr:3
- The authenticators used to attain this level MUST conform with the Credential Level
CL2
rules specified under the Trusted Digital Identity Framework [TDIF] Authentication Credential Requirements specification.
- The authenticators used to attain this level MUST conform with the Credential Level
READ operations SHALL only be allowed where at least an LoA of 2 has been achieved during the establishment of consent.
WRITE operations SHALL only be allowed where:
- At least an LoA of 3 has been achieved during the establishment of consent, or
- At least an LoA of 2 has been achieved during the establishment of consent and a subsequent challenge/response has resulted in an LoA of 3 being achieved within the lifespan of the current Access Token.
Transaction Security
Use of TLS
All HTTP calls MUST be made using HTTPS incorporating TLS >= 1.2.
Use of MTLS
All back-channel communication between Data Recipient Software Product and Data Holder systems MUST incorporate, unless stated otherwise, [MTLS] as part of the TLS handshake:
- The presented Client transport certificate MUST be issued by the CDR Certificate Authority (CA). The Server MUST NOT trust Client transport certificates issued by other authorities.
- The presented Server transport certificate MUST be issued by the CDR Certificate Authority (CA). The Client MUST NOT trust Server transport certificates issued by other authorities.
End points for transferring CDR Data that are classified as not requiring authentication do not require the use of [MTLS].
Holder of Key Mechanism
[MTLS] MUST be supported as a Holder of Key (HoK) Mechanism.
Note that, by implication, resource requests MUST be validated to ensure the client certificate and access token match.
OAUTB SHALL NOT be supported due to a lack industry support.
[MTLS] HoK allows issued tokens to be bound to a client certificate as specified in section 3 of [MTLS].
Ciphers
Only the following cipher suites SHALL be permitted in accordance with section 8.5 of [FAPI-1.0-Advanced]:
- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
Certificate Management
Issued by the Register for Data Holders
Certificate | Function | Notes |
---|---|---|
Server Certificate(s) | Certificate is issued to a FQDNSecures the following endpoints:- Resource endpoints- InfoSec endpoints- Admin endpoints | It will be up to the DH on how these endpoints are segregated. They may all be on the one domain (so only one certificate required) or could be separated. |
Issued by the Register CA for Data Recipients
Certificate | Function | Notes |
---|---|---|
Client Certificate | Secures the following:- Consuming Register APIs- Consuming Data Holder APIs | |
Server Certificate(s) | Certificate is issued to a FQDN. Secures the following:- CDR Arrangement Revocation endpoint - JWKS endpoint |
ADRs may choose to secure their endpoints with the Register CA issued certificate or a certificate issued by a public CA. |
CDR Certificate Authority
DigiCert acts as the certificate authority that issues and manages certificates to CDR participants as directed by the ACCC Register in its capacity as the CDR Registrar.
Certificate Trust Model
The CDR utilises a private certificate trust chain for all Register CA secured endpoints being hosted by Data Holders, Data Recipients and the Register.
This trust chain encompasses a set of root and intermediate CAs issued for the test and production environments.
Test Environment | Details provided to participants when they begin CTS process |
Production Environment | CA Root ProductionCA Intermediate Production |
Certificate Signing Request Profile
When requesting the Register CA certificates, certificate signing requests will need to be provided, conforming to the following profile:
CSR Field | Required | Server | Client |
---|---|---|---|
Common Name (CN) | Mandatory | Primary DNS Namee.g. api1.test.entity.com | Software Product Name |
SAN | Optional | Secondary DNS Name(s) e.g. api2.test.entity.com | N/A |
Organization (O) | Mandatory | Brand Name | Brand Name |
Organizational Unit (OU) | Mandatory | Consumer Data Right | Consumer Data Right |
Country (C) | Mandatory | Country of participante.g. AU | Country of participante.g. AU |
State (ST) | Optional | State of the Participante.g. New South Wales | State of the Participante.g. New South Wales |
Locality (L) | Optional | Locality of the Participante.g. Sydney | Locality of the Participante.g. Sydney |
Email Address | Optional | Participant's email address to be displayed in the issued certificate | Participant's email address to be displayed in the issued certificate |
Signature Algorithm | Mandatory | SHA256 | SHA256 |
Key Algorithm | Mandatory | RSA | RSA |
Key Size | Mandatory | 2048 | 2048 |
Note: optional values, if provided, will be validated to be correct.
Please refer to the Register onboarding guide for further information on certificate issuance.
Certificate Usage
Further details on the Register CA issued certificates can be found in the ACCC Certificate Practice Statement V1.0.
Certificate Validation
Certificate validation must check:
1. Checking for certificate validity
Verify private key signature is mathematically linked to the presented public key certificate, presented certificate identifies trusted User/Application and/or Service and certificate is both valid and not revoked.
2. Issuer‐to‐subject name chaining
Signatures from Issuing CA’s and associated CA public key certificates are trusted, valid and not revoked.
3. Policy and key use constraints
Each certificate has the applicable and appropriate x.509 certificate extensions, e.g. CA and CRL signing, Digital Signing, Client and Server Authentication, etc.
4. Revocation Status
Status is checked through Certificate Revocation Lists (CRL) or Online Certificate Status Protocol (OCSP) responders, identified in each certificate in the chain.
The Certificate Practice Statement provides details for DigiCert's certificate validation requirements and a summary has been provided in the CDR Support Portal article: Certificate Validation.
OCSP stapling
The use of OCSP Stapling within the CDR ecosystem is not recommended.
CORS
Cross-origin resource sharing (CORS) protections must be disabled (ie. Access-Control-Allow-Origin
set to "*") for all unauthenticated end points unless specifically stated otherwise in these standards or in a normative reference.
Request Object
Non-Normative Example - acr as an Essential Claim
#Decoded Request Object JWT
{
"iss": "s6BhdRkqt3",
"exp": 1516239322,
"aud": "https://www.recipient.com.au",
"response_type": "code id_token",
"client_id": "s6BhdRkqt3",
"redirect_uri": "https://www.recipient.com.au/coolstuff",
"scope": "openid profile bank:accounts.basic:read
bank:accounts.detail:read",
"nonce": "n-0S6_WzA2Mj",
"state": "af0ifjsldkj",
"claims": {
"sharing_duration": 7776000,
"cdr_arrangement_id": "02e7c9d9-cfe7-4c3e-8f64-e91173c84ecb",
"id_token": {
"acr": {
"essential": true,
"values": ["urn:cds.au:cdr:3"]
}
},
"userinfo": {
"given_name": null,
"family_name": null
}
}
}
Non-Normative Example - FAPI 1.0 Final Phase 3 Obligation
#Decoded Request Object JWT
{
"iss": "s6BhdRkqt3",
"exp": 1680832800,
"nbf": 1680829200,
"aud": "https://www.recipient.com.au",
"response_type": "code",
"response_mode": "jwt",
"client_id": "s6BhdRkqt3",
"redirect_uri": "https://www.recipient.com.au/coolstuff",
"scope": "openid profile bank:accounts.basic:read
bank:accounts.detail:read",
"nonce": "n-0S6_WzA2Mj",
"state": "af0ifjsldkj",
"claims": {
"sharing_duration": 7776000,
"cdr_arrangement_id": "02e7c9d9-cfe7-4c3e-8f64-e91173c84ecb",
"id_token": {
"acr": {
"essential": true,
"values": ["urn:cds.au:cdr:3"]
}
},
"userinfo": {
"given_name": null,
"family_name": null
}
},
"code_challenge": "ZTA2ZmFkYjUyMjA2NDNhZGVkYzE1M2I5OTYzZDAxNGI2NWNiZjAxMzVhNDlmMTk2NTlmZWE0OWVhOTQxZjhmZg==",
"code_challenge_method": "S256"
}
The Request Object is a signed and encoded JWT specified in section 6.1 of [OIDC]. As per [FAPI-1.0-Advanced] section 5.2.2, the request
parameter MUST be present on requests to the [OIDC] Hybrid Authorisation End Point. The Request Object enables [OIDC] requests to be passed in a single and self-contained parameter.
Request Objects MUST be signed by Data Recipient Software Products as specified in section 8.6 of [FAPI-1.0-Advanced].
Request Object references MUST be supported if the Data Holder supports Pushed Authorisation Requests (PAR).
Requesting Sharing Duration
To facilitate the specification of the duration for consent to share CDR data that is approved by the consumer, a mechanism for the Data Recipient Software Product to specify a sharing duration to the Data Holder is required.
To accomplish this, the Data Holder MUST support an additional claim in the authorisation request object named sharing_duration
. The sharing_duration
claim MUST be handled as follows:
- The
sharing_duration
parameter is a number - The value of the
sharing_duration
parameter will contain the requested duration for sharing, in seconds. - If the
sharing_duration
value exceeds one year then a duration of one year will be assumed. - If the
sharing_duration
value is less than or equal to 24 hours, then one-time collection will be assumed, and a Refresh Token SHOULD be provided by the Data Holder - If the
sharing_duration
value is zero or absent then once off access will be assumed and only an Access Token (without a Refresh Token) will be provided on successful authorisation. - If a Refresh Token is issued for one-time collection the Data Recipient Software Product MUST call the Data Holder’s revocation endpoint after successful collection of the CDR data.
- If the
sharing_duration
value is negative then the authorisation SHOULD fail.
Note that the period of one year
in the above statements SHOULD be interpreted as 365, 24 hour days (or 31,536,000 seconds).
The Data Recipient Software Product is able to obtain the expiration of sharing via the sharing_expires_at
claim.
Specifying an existing arrangement
Provided a Data Holder supports PAR, they MUST also support the cdr_arrangement_id
claim provided in the Request Object sent to the PAR End Point. The Data Recipient Software Product MAY provide the cdr_arrangement_id
claim in the Request Object sent to the PAR End Point.
If a Data Recipient Software Product provides the cdr_arrangement_id
claim in the request object to the Data Holder's PAR End Point, the Data Holder MUST revoke any existing tokens related to the arrangement once the new consent is successfully established and a new set of tokens has been provided to the Data Recipient Software Product.
Request Object Submission
In addition:
- Request Object references SHALL NOT be supported in any mode of use other than [PAR]. If a Data Holder does not support [PAR], it MUST NOT support Request Object references.
- The Request URI is intended to be a single-use reference to the respective request object.
- The Request URI MUST expire between 10 seconds and 90 seconds
- Data Recipient Software Products MAY provide an existing
cdr_arrangement_id
claim in an authorisation request object to establish a new consent under an existing arrangement - Data Holders MUST revoke existing refresh tokens and access tokens when a
cdr_arrangement_id
is provided in the Request Object but only after successful authorisation - If the
cdr_arrangement_id
is not related to the consumer being authenticated it MUST be rejected - If the
cdr_arrangement_id
is not recognised by to the Data Holder it MUST be rejected
Data Holders
Data Holders MUST support Pushed Authorisation Requests (PAR) via the pushed authorisation end point according to [PAR].
- Data Holders MUST support [RFC9126] (PAR) using [PKCE] ([RFC7636]) with S256 as the code challenge method in accordance with [FAPI-1.0-Advanced] section 5.2.2.
- Data Holders MUST require PAR for authorisation request data in accordance with [RFC9126] where "require_pushed_authorization_requests" parameter is set to "true".
- Data Holders MUST require the request object to contain an "exp" claim that has a lifetime of no longer than 60 minutes after the "nbf" claim in accordance with [FAPI-1.0-Advanced] section 5.2.2.
- Authorisation request data MUST only be accepted using PAR.
- Data Holders MUST reject authorisation request containing "request" parameter
- Data Holders MUST reject the reuse of "request_uri" values.
Data Recipient Software Products
- Data Recipients Software Products MUST send request object containing a "nbf" claim and an "exp" claim that has a lifetime of no longer than 60 minutes after the "nbf" claim.
- Data Recipient Software Products MUST ONLY use a "request_uri" value once
- Data Recipients MUST ONLY send authorisation request data using [RFC9126] (PAR) and use [PKCE] ([RFC7636]) in accordance with [FAPI-1.0-Advanced].
- Data Recipients Software Products MUST support [PKCE] ([RFC7636]) and MUST use S256 as the code challenge method.
Security Endpoints
OpenID Provider Configuration End Point
Non-Normative Example
## Request
GET /.well-known/openid-configuration HTTP/1.1
Host: www.dh.com.au
## Response - FAPI 1.0 Final Phase 3 Obligations
HTTP/1.1 200 OK
Content-Type: application/json
{
"acr_values_supported": ["urn:cds.au:cdr:2","urn:cds.au:cdr:3"],
"authorization_endpoint": "https://www.dh.com.au/authorise",
"claims_supported": ["name", "given_name", "family_name", "acr", "auth_time", "sub", "refresh_token_expires_at", "sharing_expires_at"],
"grant_types_supported": ["authorization_code", "client_credentials", "urn:openid:params:modrna:grant-type:backchannel_request"],
"id_token_encryption_alg_values_supported": [ "RSA-OAEP", "RSA-OAEP-256", "dir", "ECDH-ES", "ECDH-ES+A128KW", "ECDH-ES+A192KW", "ECDH-ES+A256KW", "A128KW", "A192KW", "A256KW", "A128GCMKW", "A192GCMKW", "A256GCMKW" ],
"id_token_encryption_enc_values_supported": [ "A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512", "A128GCM", "A192GCM", "A256GCM" ],
"id_token_signing_alg_values_supported": ["ES256", "PS256"],
"issuer": "https://www.dh.com.au",
"jwks_uri": "https://www.dh.com.au/jwks",
"registration_endpoint": "https://www.dh.com.au/register",
"request_object_signing_alg_values_supported": ["ES256", "PS256"],
"response_modes_supported": ["fragment", "jwt"],
"response_types_supported": ["code id_token", "code"],
"subject_types_supported": ["pairwise"],
"scopes_supported": ["openid", "profile", "..."],
"token_endpoint": "https://www.dh.com.au/token",
"token_endpoint_auth_methods_supported": ["private_key_jwt"],
"token_endpoint_auth_signing_alg_values_supported": ["ES256", "PS256"],
"userinfo_endpoint": "https://www.dh.com.au/userinfo",
"code_challenge_methods_supported": ["S256"],
"introspection_endpoint": "https://www.dh.com.au/introspect",
"revocation_endpoint": "https://www.dh.com.au/revoke",
"tls_client_certificate_bound_access_tokens": true,
"pushed_authorization_request_endpoint": "https://data.holder.com.au/par",
"require_pushed_authorization_requests": true,
"authorization_encryption_alg_values_supported": ["RSA-OAEP", "RSA-OAEP-256"],
"authorization_encryption_enc_values_supported": ["A256GCM", "A128CBC-HS256"],
"authorization_signing_alg_values_supported": ["ES256", "PS256"],
"cdr_arrangement_revocation_endpoint": "https://data.holder.com.au/arrangements/revoke"
}
Description | Value |
---|---|
Hosted By | Data Holder |
Transport Security | TLS |
Client Authentication Required | No |
Bearer Token Required | No |
Data Holders MUST make their OpenID Provider Metadata available via a configuration end point as outlined in Section 3 and 4 of the OpenID Connect Discovery standards [OIDD].
This endpoint does not require CORS.
At a minimum, the Data Holder metadata MUST include:
acr_values_supported
: The supported ACR valuesauthorization_endpoint
: URL of the Authorization End Pointclaims_supported
: The list of supported claimsgrant_types_supported
: The list of the OAuth 2.0 Grant Type values supportedid_token_encryption_alg_values_supported
: The list of the supported JWE algorithms for securing the issued ID tokens. Must conform to [FAPI-1.0-Advanced] and [OIDD]. Required for Data Holders supporting OIDC Hybrid Flowid_token_encryption_enc_values_supported
: The list of the supported JWE encryption methods for securing the issued ID tokens. Required for Data Holders supporting OIDC Hybrid Flowid_token_signing_alg_values_supported
: The list of the JWS signing algorithms (alg
values) supportedissuer
: URL that the Data Holder asserts as its Issuer Identifierjwks_uri
: The JSON Web Key Set for the data holderregistration_endpoint
: URL of the Client Registration End Pointrequest_object_signing_alg_values_supported
: The list of the JWS signing algorithms (alg
values) supported for signing request objects.response_modes_supported
: The list of the OAuth 2.0response_mode
values supportedresponse_types_supported
: The list of the OAuth 2.0response_type
values supportedscopes_supported
: The list of supported scopessubject_types_supported
: list of the Subject Identifier types supportedtoken_endpoint
: URL of the Token End Pointtoken_endpoint_auth_methods_supported
: The list of Client Authentication methods supported by the Token Endpointtoken_endpoint_auth_signing_alg_values_supported
: The list of the JWS signing algorithms (alg
values) supported by the token endpoint for the signature on the JWT [JWT] used to authenticate the client at the token endpoint for the "private_key_jwt" authentication methoduserinfo_endpoint
: URL of the UserInfo End Point
code_challenge_methods_supported
: JSON array containing a list of [PKCE (RFC7636)] code challenge methods supportedintrospection_endpoint
: URL of the Introspection End Pointrevocation_endpoint
: URL of the Revocation End Point
tls_client_certificate_bound_access_tokens
: Indicates support for mutual-TLS client certificate-bound access tokens. Value MUST be set totrue
pushed_authorization_request_endpoint
: URL of the Pushed Authorisation End Point used to support [PAR]require_pushed_authorization_requests
: Boolean parameter indicating whether the authorization server accepts authorization request data only via PAR
authorization_encryption_alg_values_supported
: A JSON array containing a list of the JWE encryption algorithms (alg
values) supported by the authorization endpoint to encrypt the response. If response encryption is used, Data Holders must support at least one of "RSA-OAEP" or "RSA-OAEP-256"
Where Data Holders support authorisation response encryption according to [JARM], the following parameter provisions MUST be supported:
authorization_encryption_enc_values_supported
: A JSON array containing a list of the JWE encryption algorithms (enc
values) supported by the authorization endpoint to encrypt the response. Required if “authorization_encryption_alg_values_supported” is provided. If response encryption is used, Data Holders must support at least one of "A256GCM" or "A128CBC-HS256"authorization_signing_alg_values_supported
: A JSON array containing a list of the JWS signing algorithms (alg
values) supported by the authorization endpoint to sign the response. Required if Authorization Code Flow (response_type “code”) is supported
In addition, the Data Holder metadata MUST also include:
cdr_arrangement_revocation_endpoint
: The URL of the CDR Arrangement Revocation End Point for consent revocation
Authorisation End Point
Non-Normative Example
This example demonstrates how an ADR may send an authorisation request object by value in the front-channel to the Data Holder.
## Request
GET /authorise?
response_type=code%20id_token&client_id=12345&
scope=openid%20profile%20bank:accounts.basic:read%20bank:accounts.detail:read&
request=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.ey ...
HTTP/1.1
Host: www.holder.com.au
## Decoded request JWT
{
"alg": "PS256",
"typ": "JWT",
"kid": "123"
}
{
"iss": "12345",
"exp": 1516239322,
"aud": "https://www.recipient.com.au",
"response_type": "code id_token",
"client_id": "12345",
"redirect_uri": "https://www.recipient.com.au/coolstuff",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read",
"state": "af0ifjsldkj",
"nonce": "n-0S6_WzA2Mj",
"claims": {
"sharing_duration": 7776000,
"userinfo": {
"given_name": {"essential": true},
"family_name": null
},
"id_token": {
"acr": {
"essential": true,
"values": ["urn:cds.au:cdr:2"]
},
"refresh_token_expires_at": {
"essential": true
},
"sharing_expires_at": {
"essential": true
}
}
}
}
Non-Normative Example - FAPI 1.0 Final Phase 3 Obligation This example demonstrates how an ADR may send a staged authorisation request (using PAR) in the back-channel to the Data Holder.
It demonstrates a FAPI 1.0 Final compliant authorisation request using the PAR to first submit the authorisation request object.
## Request
GET /authorize?client_id=12345&
scope=openid&
request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A6esc_11ACC5bwc014ltc14eY22c
HTTP/1.1
Host: www.holder.com.au
Description | Value |
---|---|
Hosted By | Data Holder |
Transport Security | TLS |
Client Authentication Required | No |
Bearer Token Required | No |
The requirements for the Authorisation End Point are specified in section 3.3.2 of [OIDC] and further specified under section 5.2.2 of [FAPI-1.0-Advanced]. This end point is invoked as part of the Hybrid Authentication flow.
This endpoint does not require CORS.
JSON Web Key Set End Point
Description | Value |
---|---|
Hosted By | Data Holder & Data Recipient Software Product |
Transport Security | TLS |
Client Authentication Required | No |
Bearer Token Required | No |
The requirements for the JWKS End Point are specified in various sections of [OIDC].
This end point is used by the Data Holder to provide the public keys they will use when required.
Data Holders MUST support a JWKS End Point.
This endpoint does not require CORS.
JWKS URIs
In addition to [FAPI-1.0-Advanced] section 8.9 from July 4th 2022, the following requirements apply:
- Data Holders and Data Recipients JWK sets MUST NOT contain multiple keys with the same "kid"
Token End Point
Description | Value |
---|---|
Hosted By | Data Holder |
Transport Security | MTLS |
Client Authentication Required | Yes |
Bearer Token Required | No |
The requirements for the Token End Point are specified in section 3.3.3 of [OIDC].
To obtain an Access Token, an ID Token, and a Refresh Token, the Data Recipient Software Product sends a Token Request to the Token End Point.
Data Holders MUST support a Token End Point.
UserInfo End Point
Description | Value |
---|---|
Hosted By | Data Holder |
Transport Security | MTLS |
Client Authentication Required | No |
Bearer Token Required | Yes |
The requirements for the UserInfo End Point are specified in section 5.3 of [OIDC].
Data Holders MUST support a UserInfo End Point.
Introspection End Point
Description | Value |
---|---|
Hosted By | Data Holder |
Transport Security | MTLS |
Client Authentication Required | Yes |
Bearer Token Required | No |
Data Holders MUST implement an Introspection End Point to allow Data Recipient Software Products to determine the status and expiry date of Refresh Tokens. The requirements for an Introspection End Point are described in section 2 of [RFC7662].
Introspection of Refresh Tokens MUST be supported.
Introspection of Access Tokens and ID Tokens MUST NOT be supported.
A Token Introspection End Point Response SHALL include, at least, the following fields:
active
: Boolean indicator of whether or not the presented token is currently active.exp
: A JSON number representing the number of seconds from 1970-01-01T00:00:00Z to the UTC expiry time.scope
: A JSON string containing a space-separated list of scopes associated with this token.cdr_arrangement_id
: A unique identifier of the CDR arrangement related to the authorisation.
A Token Introspection End Point Response MAY include claims defined in Section 2.2 of [RFC7662] but username
SHALL NOT be allowed.
Token Revocation End Point
Description | Value |
---|---|
Hosted By | Data Holder |
Transport Security | MTLS |
Client Authentication Required | Yes |
Bearer Token Required | No |
Requirements for Data Holder implementations
Data Holders MUST implement a Token Revocation End Point as described in section 2 of [RFC7009].
The Revocation End Point serves as a revocation mechanism that allows a Data Recipient Software Product to invalidate its tokens as required to allow for token clean up.
Revocation of Refresh Tokens and Access Tokens MUST be supported.
CDR Arrangement Revocation End Point
Non-Normative Example: Data Holder end point
(Data Recipients calling Data Holders)
Request
POST https://data.holder.com.au/arrangements/revoke
HTTP/1.1
Host: data.holder.com.au
Content-Type: application/x-www-form-urlencoded
client_id=s6BhdRkqt3&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...&
cdr_arrangement_id=5a1bf696-ee03-408b-b315-97955415d1f0
Description | Value |
---|---|
Hosted By | Data Holder & Data Recipient Software Product |
Transport Security | MTLS for Data Holders, TLS for Data Recipient Software Products |
Client Authentication Required | Yes (for Data Holders verifying Data Recipient Software Products) |
Bearer Token Required | Yes (for Data Recipient Software Products verifying Data Holders) |
HTTP Method: POST
Data Holder Path: The cdr_arrangement_revocation_endpoint
defined using OIDC Discovery
Data Recipient Software Product Path: <RecipientBaseUri>/arrangements/revoke
where <RecipientBaseUri>
is registered with the CDR Register.
Data Holders and Data Recipient Software Products MUST implement a CDR Arrangement Revocation End Point that can be used to revoke an existing sharing arrangement.
CDR Arrangement Form Parameter method
The request MUST include the following parameters using the application/x-www-form-urlencoded
format in the HTTP request entity-body:
cdr_arrangement_id
: The ID of the arrangement that the client wants to revoke.
CDR Arrangement JWT method
The request MUST include the following parameters using the application/x-www-form-urlencoded format in the HTTP request entity-body:
cdr_arrangement_jwt
: A signed JWT that includes thecdr_arrangement_id
.cdr_arrangement_jwt
: A newly signed JWT with the following parameters in accordance with [JWT]:cdr_arrangement_id
: The ID of the arrangement that the client wants to revoke.
The cdr_arrangement_jwt
SHOULD include all parameters in accordance with Data Holders calling Data Recipients using Self-Signed JWT Client Authentication.
Data Holder hosted endpoint
The location of the Data Holder CDR Arrangement Revocation End Point is determined by the cdr_arrangement_revocation_endpoint
in the Data Holder's OpenID Provider metadata.
This end point will be implemented according to the following:
- Data Holders MUST only support "CDR Arrangement Form Parameter" method
- Data Recipient Software Products MUST revoke consent by calling the CDR Arrangement Revocation End Point with a valid CDR Arrangement ID
- Data Holders MUST publish their CDR Arrangement Revocation End Point using their OpenID Provider Metadata Discovery End Point
- Consent revocation MUST also revoke associated refresh and/or access tokens
- If the
cdr_arrangement_id
is not related to the client making the call it MUST be rejected
Non-Normative Example: Data Recipient end point
Until July 31st 2022
(Data Holders calling Data Recipients)
Request
POST https://data.recipient.com.au/arrangements/revoke
HTTP/1.1
Host: data.recipient.com.au
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
cdr_arrangement_id=5a1bf696-ee03-408b-b315-97955415d1f0
Non-Normative Example: Data Recipient end point
From March 31st 2022
(Data Holders calling Data Recipients)
Request
POST https://data.recipient.com.au/arrangements/revoke
HTTP/1.1
Host: data.recipient.com.au
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyNDU2In0.ey ...
cdr_arrangement_id=5a1bf696-ee03-408b-b315-97955415d1f0&
cdr_arrangement_jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjEyNDU2In0.ey ...
## Decoded cdr_arrangement_jwt JWT
{
"typ": "JWT",
"alg": "PS256",
"kid":"12456"
}
{
"cdr_arrangement_id": "5a1bf696-ee03-408b-b315-97955415d1f0",
"iss":"dataholderbrand-123",
"sub":"dataholderbrand-123",
"aud":"https://data.recipient.com.au/arrangements/revoke",
"iat":1516239022,
"exp":1516239322,
"jti":"dba86502-7cf5-4719-9638-c5339a0ddb06"
}
Data Recipient hosted endpoint
The location of the Data Recipient Software Product CDR Arrangement Revocation End Point is determined by the RecipientBaseURI
provided by the Data Recipient Software Product in the client Software Statement Assertion (SSA).
This end point will be implemented according to the following:
- Data Recipient Software Products MUST expose their CDR Arrangement Revocation End Point under their
recipient_base_uri
published in their Software Statement Assertion. - Data Holders must be authenticated when they call this end point according to the guidance in the Client Authentication section.
- If the
cdr_arrangement_id
is not related to the client making the call it MUST be rejected. - From March 31st 2022, Data Recipients MUST support the "CDR Arrangement JWT" method.
- From July 31st 2022, Data Holders MUST send the
cdr_arrangement_id
using the "CDR Arrangement JWT" method. - Data Holders MAY additionally send a duplicate of the
cdr_arrangement_id
as a form parameter. - Data Recipient Software Products MUST NOT reject requests including the
cdr_arragement_id
as a form parameter. - If the
cdr_arrangement_id
is presented as a form parameter, Data Recipient Software Products SHOULD validate it is identical to thecdr_arrangement_id
presented in the "CDR Arrangement JWT". - From November 15th 2022, if the
cdr_arrangement_id
is presented as a form parameter, Data Recipient Software Products MUST validate it is identical to thecdr_arrangement_id
presented in the "CDR Arrangement JWT". - From November 15th 2022, if the Self-Signed JWT claims are presented in the "CDR Arrangement JWT", Data Recipient Software Products MUST validate in accordance with Data Holders calling Data Recipients using Self-Signed JWT Client Authentication.
Response Codes
The following responses are in addition to error responses covered by normative references. Error scenarios in the following table MUST use the error structure defined in the Payload Conventions.
Response Code | Situation | Description |
---|---|---|
204 No Content | Success | The sharing arrangement has been revoked successfully |
422 Unprocessable Entity | Invalid Arrangement ID | The client submitted an invalid arrangement identifier or the identifier could not be found. The server MUST respond with Invalid Consent Arrangement. |
Revoking consent
Data Recipient Software Products MUST use the Data Holder's CDR Arrangement Revocation End Point with a valid cdr_arrangement_id
to notify the Data Holder when consent is revoked by the consumer via the Data Recipient Software Product.
Data Holder's MUST use the Data Recipient Software Product's CDR Arrangement Revocation End Point with a valid cdr_arrangement_id
to notify the Data Recipient Software Product when consent is revoked by the consumer via the Data Holder.
Pushed Authorisation End Point
Non-Normative Example
Utilising RFC9126 and OIDC Hybrid FlowRequest
POST /par HTTP/1.1
Host: data.holder.com.au
Content-Type: application/x-www-form-urlencoded
request=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.ey...
Decoded Request
This example shows an authorisation request using the OIDC Hybrid Flow
{
"iss": "s6BhdRkqt3",
"exp": 1516239322,
"aud": "https://www.recipient.com.au",
"response_type": "code id_token",
"client_id": "s6BhdRkqt3",
"redirect_uri": "https://www.recipient.com.au/coolstuff",
"scope": "openid profile bank:accounts.basic:read
bank:accounts.detail:read",
"nonce": "n-0S6_WzA2Mj",
"state": "af0ifjsldkj",
"claims": {
"sharing_duration": 7776000,
"cdr_arrangement_id": "02e7c9d9-cfe7-4c3e-8f64-e91173c84ecb",
"id_token": {
"acr": {
"essential": true,
"values": ["urn:cds.au:cdr:3"]
}
},
"userinfo": {
"given_name": null,
"family_name": null
}
}
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"request_uri": "urn:data.holder.com.au:bwc4JK-ESC0w8acc191e-Y1LTC2",
"expires_in": 3600
}
Authorise
## The request_uri is used by the ADR in the subsequent authorisation request as follows
## (note this example is pre-RFC using Draft 01 of the PAR standard, hence it includes
## the mandatory oAuth parameters as per FAPI R/W for confidential clients must be
## replayed in the request URL):
GET /authorise?client_id=s6BhdRkqt3&
response_type=code%20id_token&
scope=openid%20profile%20bank:accounts.basic:read%20bank:accounts.detail:read&
request_uri=urn%3Adata.holder.com.au%3Abwc4JK-ESC0w8acc191e-Y1LTC2
HTTP/1.1
Host: data.holder.com.au
Non-Normative Example - FAPI 1.0 Final Phase 3 Obligations
Utilising FAPI 1.0 Final, PAR RFC9126, PKCE, JARM and Authorization Code FlowRequest
POST /par HTTP/1.1
Host: data.holder.com.au
Content-Type: application/x-www-form-urlencoded
request=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.ey...
Decoded Request - FAPI 1.0 Final Phase 3 Obligation
This example shows an authorisation request using the Authorisation Code Flow (FAPI 1.0 migration Phase 3)
{
"iss": "s6BhdRkqt3",
"exp": 1680832800,
"nbf": 1680829200,
"aud": "https://www.recipient.com.au",
"response_type": "code",
"response_mode": "jwt",
"client_id": "s6BhdRkqt3",
"redirect_uri": "https://www.recipient.com.au/coolstuff",
"scope": "openid profile bank:accounts.basic:read
bank:accounts.detail:read",
"nonce": "n-0S6_WzA2Mj",
"state": "af0ifjsldkj",
"claims": {
"sharing_duration": 7776000,
"cdr_arrangement_id": "02e7c9d9-cfe7-4c3e-8f64-e91173c84ecb",
"id_token": {
"acr": {
"essential": true,
"values": ["urn:cds.au:cdr:3"]
}
},
"userinfo": {
"given_name": null,
"family_name": null
}
},
"code_challenge": "ZTA2ZmFkYjUyMjA2NDNhZGVkYzE1M2I5OTYzZDAxNGI2NWNiZjAxMzVhNDlmMTk2NTlmZWE0OWVhOTQxZjhmZg==",
"code_challenge_method": "S256"
}
Response - FAPI 1.0 Final Phase 3 Obligation
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"request_uri": "urn:data.holder.com.au:bwc4JK-ESC0w8acc191e-Y1LTC2",
"expires_in": 3600
}
Authorise - FAPI 1.0 Final Phase 3 Obligation
## This is used by the ADR in the subsequent authorisation request as follows
## (this example uses PAR RFC 9126 and Authorization Code Flow):
GET /authorise?client_id=s6BhdRkqt3&
request_uri=urn%3Adata.holder.com.au%3Abwc4JK-ESC0w8acc191e-Y1LTC2
HTTP/1.1
Host: data.holder.com.au
Authorisation response using JARM response encryption - FAPI 1.0 Final Phase 3 Obligation
eyJraWQiOiIwZWQ3YTNkZi1hMGJlLTRhZjQtOTk0YS1jNDBhODc0ODQwNjMiLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiIxMjM0NSIsImNvZGUiOiJpMVdzUm4xdUIxIiwiaXNzIjoiaHR0cHM6Ly9kYXRhLmhvbGRlci5jb20uYXUvIiwic3RhdGUiOiJhZjBpZmpzbGRraiIsImV4cCI6MTY2NzI2ODAwMH0.flBD3bTUHUFiNMbfgt-Uqt4wnEFHY79QYx0f9qrqPGPZLB-RBb-F20aPTyB9XaJ1JJ3ie1m0YxdMC7t6aiXSchZZQXBmYpIjvlbTceOVBYlr88llqeLAfQ5nCDD4p2axqyedpA83OgPF8i_Ngw0oRsCwBTueo6C40wYeI3ZT_n0hucQqGHcSoR1im7IY1rY0x99EZjJI3pxVtGwst6e-msomipnYedCdkNuPHE_Rnj0g897zi_NdK6m3dhxcpwaoMXcaYfMkkkzTlbz5_Ic9lWMx_z01C2wRNjRBArEJsNXW0Q8Vdhk_vtOAmO92Pr3cI8BpTr5KdY2O1iD-yRnkug
## Decoded Response
{
"kid": "0ed7a3df-a0be-4af4-994a-c40a87484063",
"alg": "PS256"
}
{
"aud": "12345",
"code": "i1WsRn1uB1",
"iss": "https://data.holder.com.au/",
"state": "af0ifjsldkj",
"exp": 1667268000
}
Description | Value |
---|---|
Hosted By | Data Holder |
Transport Security | MTLS |
Client Authentication Required | Yes |
Bearer Token Required | No |
Data Holders MUST support Pushed Authorisation Requests (PAR) via the pushed authorisation end point according to [PAR].
Data Recipient Software Products MUST send authorisation requests using [PAR] if supported by the Data Holder.
The Data Holder response provides the Data Recipient Software Product with a Request URI in the response. The Request URI is then passed to the Data Holder’s Authorisation End Point to initiate an authorisation flow.
Dynamic Client Registration Endpoints
Data Holders MUST expose the following endpoints in accordance with [DCR].
For more details of these endpoints see the DCR APIs section.
For additional statements on the operation of these endpoint during client registration see the Client Registration section.
HTTP Verb | Auth Server Support | TLS-MA | HoK | Grant Type | Access Token Scope |
---|---|---|---|---|---|
POST /register | Required | N/A | None | ||
GET /register/{clientID} | Required | Client Credentials | cdr:registration | ||
PUT /register/{clientID} | Required | Client Credentials | cdr:registration | ||
DELETE /register/{clientID} | Optional | Client Credentials | cdr:registration |
Additional statements regarding these endpoints:
- During registration management requests, Data Holders MUST validate that the scope of access tokens provided includes
cdr:registration
- Registration requests and responses must conform to the specification in the DCR APIs section.
- Any fields the Data Holder does not support MUST be ignored without error.
- Registrations MUST only be updated via a PUT operation on the registration endpoint
- POST and PUT operations MUST accept the SSA payload
- Update (PUT) operations are to be used for one of two scenarios:
- The client has updated their registration details on the CDR Register and updates this information to the data holder brands
- A new version of the SSA has been released and the client updates this information to the data holder brands
Register Endpoints
The CDR Register exposes an OIDC Configuration Endpoint with associated JWKS and token endpoints to facilitate issuance of access tokens to consume the protected Register APIs.
Retrieve CDR Register OIDC Discovery Endpoint
GET /.well-known/openid-configuration HTTP/1.1
Host: cdr.register
## Response
{
"issuer": "https://cdr.register/idp",
"jwks_uri": "https://cdr.register/idp/.well-known/openid-configuration/jwks",
"token_endpoint": "https://cdr.register/idp/connect/token",
"claims_supported": ["sub"],
"id_token_signing_alg_values_supported": ["PS256"],
"subject_types_supported": ["public"],
"scopes_supported": ["cdr-register:bank:read"],
"response_types_supported": ["token"],
"grant_types_supported": ["client_credentials"],
"token_endpoint_auth_methods_supported": ["private_key_jwt"],
"tls_client_certificate_bound_access_tokens": true,
"request_object_signing_alg_values_supported": ["PS256"]
}
Participant Endpoints
OIDC Discovery Configuration Endpoint
<InfoSecBaseUri>/.well-known/openid-configuration
Participants will be required to register base URIs against each of their brands to facilitate the implementation of the Consumer Data Standards
Base URI | DH Brand | ADR Brand | Description |
---|---|---|---|
PublicBaseUri | Base URI for the Consumer Data Standard public endpoints. This should encompass all endpoints not requiring authentication. Data Holders designated for the Energy sector are not required to expose energy product reference endpoints via their public base URI and are not required, but MAY, provide a redirect to the product reference endpoints hosted by the designated data holder. |
||
ResourceBaseUri | Base URI for the Consumer Data Standard resource endpoints. This should encompass all CDS resource endpoints requiring authentication | ||
InfoSecBaseUri | Base URI for the Consumer Data Standard InfoSec endpoints. This provides ADRs reference to the OIDC Discovery Endpoint | ||
AdminBaseUri | Base URI for the Consumer Data Standard admin endpoints called by the CDR Register | ||
ExtensionBaseUri | Base URI for the Data Holder extension endpoints to the Consumer Data Standard (optional) | ||
RevocationUri | Used for consent withdrawal notification from a Data Holder and is populated in the SSA | ||
RecipientBaseUri | Base URI for the Consumer Data Standard Data Recipient Software Product endpoints. This should be the base to provide reference to Data Recipient Endpoints | ||
JwksUri | DH: Used for client authentication for DH -> DRSP communication and is populated in the GetDataHolderBrands API DR: Used for client authentication for DRSP -> DH & Register communication and is populated in the SSA |
DCR APIs
This specification defines the APIs for Data Holders exposing Dynamic Client Registration endpoints.
DCR OpenAPI Specification (JSON) |
DCR OpenAPI Specification (YAML) |
Register Data Recipient oAuth Client
Code samples
POST https://data.holder.com.au/register HTTP/1.1
Host: data.holder.com.au
Content-Type: application/jwt
Accept: application/json
const fetch = require('node-fetch');
const inputBody = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const headers = {
'Content-Type':'application/jwt',
'Accept':'application/json'
};
fetch('https://data.holder.com.au/register',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
POST /register
Register a client using a CDR Register issued Software Statement Assertion.
This endpoint does not require CORS.
Body parameter
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Endpoint Version
Version | Versioning is not supported for this endpoint |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | ClientRegistrationRequest | mandatory | The registration request JWT to be used to register with a Data Holder. |
Example responses
201 Response
{
"client_id": "2cfefa98-7d4a-4bcb-95da-47063b84d410",
"client_id_issued_at": 1574398833,
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"id_token_encrypted_response_alg": "RSA-OAEP",
"id_token_encrypted_response_enc": "A256GCM",
"authorization_signed_response_alg": "PS256",
"authorization_encrypted_response_alg": "RSA-OAEP",
"authorization_encrypted_response_enc": "A128CBC-HS256",
"request_object_signing_alg": "PS256",
"software_statement": "string",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created | Client registration success | RegistrationProperties |
400 | Bad Request | Request failed due to client error | RegistrationError |
Get oAuth Client Registration
Code samples
GET https://data.holder.com.au/register/{ClientId} HTTP/1.1
Host: data.holder.com.au
Accept: application/json
Authorization: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'Authorization':'string'
};
fetch('https://data.holder.com.au/register/{ClientId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /register/{ClientId}
Get a Client Registration for a given Client ID.
Endpoint Version
Version | Versioning is not supported for this endpoint |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
ClientId | path | string | mandatory | The client ID issued by the target Data Holder |
Authorization | header | string | mandatory | An Authorisation Token as per [RFC6750] |
Example responses
200 Response
{
"client_id": "2cfefa98-7d4a-4bcb-95da-47063b84d410",
"client_id_issued_at": 1574398833,
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"id_token_encrypted_response_alg": "RSA-OAEP",
"id_token_encrypted_response_enc": "A256GCM",
"authorization_signed_response_alg": "PS256",
"authorization_encrypted_response_alg": "RSA-OAEP",
"authorization_encrypted_response_enc": "A128CBC-HS256",
"request_object_signing_alg": "PS256",
"software_statement": "string",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Client registration retrieval success | RegistrationProperties |
401 | Unauthorized | Request failed due to unknown or invalid Client or invalid access token | None |
403 | Forbidden | The client does not have permission to read, update or delete the Client | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
401 | WWW-Authenticate | string | The Response Header Field as per [RFC6750] |
Update Data Recipient Registration
Code samples
PUT https://data.holder.com.au/register/{ClientId} HTTP/1.1
Host: data.holder.com.au
Content-Type: application/jwt
Accept: application/json
Authorization: string
const fetch = require('node-fetch');
const inputBody = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const headers = {
'Content-Type':'application/jwt',
'Accept':'application/json',
'Authorization':'string'
};
fetch('https://data.holder.com.au/register/{ClientId}',
{
method: 'PUT',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
PUT /register/{ClientId}
Update a Client Registration for a given Client ID.
Body parameter
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Endpoint Version
Version | Versioning is not supported for this endpoint |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
ClientId | path | string | mandatory | The client ID issued by the target Data Holder |
Authorization | header | string | mandatory | An Authorisation Token as per [RFC6750] |
body | body | ClientRegistrationRequest | mandatory | The registration request JWT to be used to register with a Data Holder. |
Example responses
200 Response
{
"client_id": "2cfefa98-7d4a-4bcb-95da-47063b84d410",
"client_id_issued_at": 1574398833,
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"id_token_encrypted_response_alg": "RSA-OAEP",
"id_token_encrypted_response_enc": "A256GCM",
"authorization_signed_response_alg": "PS256",
"authorization_encrypted_response_alg": "RSA-OAEP",
"authorization_encrypted_response_enc": "A128CBC-HS256",
"request_object_signing_alg": "PS256",
"software_statement": "string",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Client registration update success | RegistrationProperties |
400 | Bad Request | Request failed due to client error | RegistrationError |
401 | Unauthorized | Request failed due to unknown or invalid Client or invalid access token | None |
403 | Forbidden | The client does not have permission to read, update or delete the Client | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
401 | WWW-Authenticate | string | The Response Header Field as per [RFC6750] |
Delete Data Recipient oAuth Client Registration
Code samples
DELETE https://data.holder.com.au/register/{ClientId} HTTP/1.1
Host: data.holder.com.au
Authorization: string
const fetch = require('node-fetch');
const headers = {
'Authorization':'string'
};
fetch('https://data.holder.com.au/register/{ClientId}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
DELETE /register/{ClientId}
Delete a Client Registration for a given Client ID.
Endpoint Version
Version | Versioning is not supported for this endpoint |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
ClientId | path | string | mandatory | The client ID issued by the target Data Holder |
Authorization | header | string | mandatory | An Authorisation Token as per [RFC6750] |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | Client deleted | None |
401 | Unauthorized | Request failed due to unknown or invalid Client or invalid access token | None |
403 | Forbidden | The client does not have permission to read, update or delete the Client | None |
405 | Method Not Allowed | Method Not Allowed. The requested method is unsupported | None |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
401 | WWW-Authenticate | string | The Response Header Field as per [RFC6750] |
Schemas
ClientRegistrationRequest
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
The registration request JWT to be used to register with a Data Holder.
Properties
Name | Type | Required | Description |
---|---|---|---|
anonymous | string(JWT) | mandatory | The registration request JWT to be used to register with a Data Holder. |
RegistrationProperties
{
"client_id": "2cfefa98-7d4a-4bcb-95da-47063b84d410",
"client_id_issued_at": 1574398833,
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"id_token_encrypted_response_alg": "RSA-OAEP",
"id_token_encrypted_response_enc": "A256GCM",
"authorization_signed_response_alg": "PS256",
"authorization_encrypted_response_alg": "RSA-OAEP",
"authorization_encrypted_response_enc": "A128CBC-HS256",
"request_object_signing_alg": "PS256",
"software_statement": "string",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
client_id | string | mandatory | Data Holder issued client identifier string |
client_id_issued_at | ExternalRef | optional | Time at which the client identifier was issued expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC |
client_name | string | mandatory | Human-readable string name of the software product to be presented to the end-user during authorization |
client_description | string | mandatory | Human-readable string name of the software product description to be presented to the end user during authorization |
client_uri | URIString | mandatory | URL string of a web page providing information about the client |
legal_entity_id | string | optional | A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Legal Entity |
legal_entity_name | string | optional | Human-readable string name of the Accredited Data Recipient Legal Entity |
org_id | string | mandatory | A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Brand |
org_name | string | mandatory | Human-readable string name of the Accredited Data Recipient to be presented to the end user during authorization |
redirect_uris | [string] | mandatory | Array of redirection URI strings for use in redirect-based flows. If used, redirect_uris MUST match or be a subset of the redirect_uris as defined in the SSA |
sector_identifier_uri | URIString | optional | URL string referencing the client sector identifier URI, used as an optional input to the Pairwise Identifier |
logo_uri | URIString | mandatory | URL string that references a logo for the client. If present, the server SHOULD display this image to the end-user during approval |
tos_uri | URIString | optional | URL string that points to a human-readable terms of service document for the Software Product |
policy_uri | URIString | optional | URL string that points to a human-readable policy document for the Software Product |
jwks_uri | URIString | mandatory | URL string referencing the client JSON Web Key (JWK) Set [RFC7517] document, which contains the client public keys |
revocation_uri | URIString | optional | URI string that references the location of the Software Product consent revocation endpoint |
recipient_base_uri | URIString | optional | Base URI for the Consumer Data Standard Data Recipient endpoints. This should be the base to provide reference to all other Data Recipient Endpoints |
token_endpoint_auth_method | Enum | mandatory | The requested authentication method for the token endpoint |
token_endpoint_auth_signing_alg | Enum | mandatory | The algorithm used for signing the JWT |
grant_types | [Enum] | mandatory | Array of OAuth 2.0 grant type strings that the client can use at the token endpoint |
response_types | [Enum] | mandatory | Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint. Response type value code is required for Authorization Code Flow. Response type value code id_token is required for OIDC Hybrid Flow. |
application_type | Enum | optional | Kind of the application. The only supported application type will be web |
id_token_signed_response_alg | Enum | mandatory | Algorithm with which an id_token is to be signed |
id_token_encrypted_response_alg | ExternalRef | conditional | JWE alg algorithm with which an id_token is to be encrypted.Required if OIDC Hybrid Flow (response type code id_token ) is registered. |
id_token_encrypted_response_enc | ExternalRef | conditional | JWE enc algorithm with which an id_token is to be encrypted.Required if OIDC Hybrid Flow (response type code id_token ) is registered. |
authorization_signed_response_alg | Enum | optional | The JWS alg algorithm required for signing authorization responses. If this is specified, the response will be signed using JWS and the configured algorithm. The algorithm “none” is not allowed.Required if response_type of “code” is registered by the client. |
authorization_encrypted_response_alg | Enum | optional | The JWE alg algorithm required for encrypting authorization responses. If unspecified, the default is that no encryption is performed.Required if “authorization_encrypted_response_enc” is included. |
authorization_encrypted_response_enc | Enum | optional | The JWE enc algorithm required for encrypting authorization responses. If “authorization_encrypted_response_alg” is specified, the default for this value is “A128CBC-HS256”. |
request_object_signing_alg | Enum | mandatory | Algorithm which the ADR expects to sign the request object if a request object will be part of the authorization request sent to the Data Holder |
software_statement | string(JWT) | mandatory | The Software Statement Assertion, as defined in CDR standards |
software_id | string | mandatory | String representing a unique identifier assigned by the Register and used by registration endpoints to identify the software product to be dynamically registered. The "software_id" will remain the same for the lifetime of the product, across multiple updates and versions |
software_roles | Enum | optional | String containing a role of the software in the CDR Regime. Initially the only value used will be data-recipient-software-product |
scope | string | mandatory | String containing a space-separated list of scope values that the client can use when requesting access tokens. |
Enumerated Values
Property | Value |
---|---|
token_endpoint_auth_method | private_key_jwt |
token_endpoint_auth_signing_alg | PS256 |
token_endpoint_auth_signing_alg | ES256 |
grant_types | client_credentials |
grant_types | authorization_code |
grant_types | refresh_token |
response_types | code |
response_types | code id_token |
application_type | web |
id_token_signed_response_alg | PS256 |
id_token_signed_response_alg | ES256 |
authorization_signed_response_alg | PS256 |
authorization_signed_response_alg | ES256 |
authorization_encrypted_response_alg | RSA-OAEP |
authorization_encrypted_response_alg | RSA-OAEP-256 |
authorization_encrypted_response_enc | A256GCM |
authorization_encrypted_response_enc | A128CBC-HS256 |
request_object_signing_alg | PS256 |
request_object_signing_alg | ES256 |
software_roles | data-recipient-software-product |
ClientRegistration
{
"iss": "CDR Software Product ID",
"iat": 1571808167,
"exp": 2147483646,
"jti": "37747cd1c10545699f754adf28b73e31",
"aud": "https://secure.api.dataholder.com/issuer",
"client_id": "2cfefa98-7d4a-4bcb-95da-47063b84d410",
"client_id_issued_at": 1574398833,
"client_name": "Mock Software",
"client_description": "A mock software product",
"client_uri": "https://www.mockcompany.com.au",
"legal_entity_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7",
"legal_entity_name": "Mock Company Pty Ltd.",
"org_id": "3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8",
"org_name": "Mock Company Brand",
"redirect_uris": [
"https://www.mockcompany.com.au/redirects/redirect1",
"https://www.mockcompany.com.au/redirects/redirect2"
],
"sector_identifier_uri": "https://www.mockcompany.com.au/sector_identifier.json",
"logo_uri": "https://www.mockcompany.com.au/logos/logo1.png",
"tos_uri": "https://www.mockcompany.com.au/tos.html",
"policy_uri": "https://www.mockcompany.com.au/policy.html",
"jwks_uri": "https://www.mockcompany.com.au/jwks",
"revocation_uri": "https://www.mockcompany.com.au/revocation",
"recipient_base_uri": "https://www.mockcompany.com.au",
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "PS256",
"grant_types": [
"client_credentials",
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"id_token_encrypted_response_alg": "RSA-OAEP",
"id_token_encrypted_response_enc": "A256GCM",
"authorization_signed_response_alg": "PS256",
"authorization_encrypted_response_alg": "RSA-OAEP",
"authorization_encrypted_response_enc": "A128CBC-HS256",
"request_object_signing_alg": "PS256",
"software_statement": "string",
"software_id": "740C368F-ECF9-4D29-A2EA-0514A66B0CDE",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration"
}
Properties
allOf
Name | Type | Required | Description |
---|---|---|---|
anonymous | object | mandatory | none |
» iss | string | mandatory | Contains the identifier for the ADR Software Product (SoftwareProductId) as defined in the CDR Register |
» iat | ExternalRef | mandatory | The time at which the request was issued by the Data Recipient expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC |
» exp | ExternalRef | mandatory | The time at which the request expires expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC |
» jti | string | mandatory | Unique identifier for the JWT, used to prevent replay of the token |
» aud | URIString | mandatory | Contains the Data Holder issuer value as described in the OIDC Discovery Document |
and
Name | Type | Required | Description |
---|---|---|---|
anonymous | RegistrationProperties | mandatory | none |
RegistrationError
{
"error": "invalid_redirect_uri",
"error_description": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
error | Enum | mandatory | Predefined error code as described in section 3.3 OIDC Dynamic Client Registration |
error_description | ASCIIString | optional | Additional text description of the error for debugging. |
Enumerated Values
Property | Value |
---|---|
error | invalid_redirect_uri |
error | invalid_client_metadata |
error | invalid_software_statement |
error | unapproved_software_statement |
Register APIs
The following section provides an overview of the Register APIs for Data Holders and Data Recipients to collect participant metadata. These endpoints are exposed by the Register and consumed by Data Holders and Data Recipients.
Register OpenAPI Specification (JSON) |
Register OpenAPI Specification (YAML) |
API | Caller | Description | MTLS | TLS | Bearer Token |
---|---|---|---|---|---|
Get Register OpenId Provider Config | Data Recipient Brand or Software Product | Discovery of CDR Register OpenID Configuration | |||
Get Register JWKS | Data Holder | Validate SSA and CDR Register authentication JWT signatures | |||
Get Data Holder Brands | Data Recipient Brand or Software Product | Discovery of Data Holder Brands and their associated endpoints | |||
Get Data Holder Brands Summary | Public Client | Discovery of Data Holder Brands and their associated public details | |||
Get Software Statement Assertion | Data Recipient Brand or Software Product | Get SSA for a Software Product to be used in Dynamic Client Registration | |||
Get Data Holder Statuses | Data Recipient | Data Holder Statuses to check validity of Data Holder | |||
Get Software Products Status | Data Holder Brand | Software Product Statuses to check validity of ADR requests | |||
Get Data Recipient Statuses | Data Holder Brand | Data Recipient Statuses to check validity of ADR requests | |||
Get Data Recipients | Data Holder Brand | Data Recipient, brand and product details to render Data Holder Consumer Dashboard |
Base URLs:
Production TLS | https://api.cdr.gov.au |
Production mTLS | https://secure.api.cdr.gov.au |
Get OpenId Provider Config
Code samples
GET https://<register-base-url>/idp/.well-known/openid-configuration HTTP/1.1
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json'
};
fetch('https://<register-base-url>/idp/.well-known/openid-configuration',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /idp/.well-known/openid-configuration
Endpoint used by participants to discover the CDR Register OpenID configuration and obtain information needed to interact with it, including its OAuth 2.0 endpoint locations.
This endpoint does not require CORS.
Endpoint Version
Version | Versioning is not supported for this endpoint |
Example responses
200 Response
{
"issuer": "string",
"jwks_uri": "string",
"token_endpoint": "string",
"claims_supported": [
"string"
],
"id_token_signing_alg_values_supported": [
"string"
],
"subject_types_supported": [
"string"
],
"code_challenge_methods_supported": [
"string"
],
"scopes_supported": [
"string"
],
"response_types_supported": [
"string"
],
"grant_types_supported": [
"string"
],
"token_endpoint_auth_methods_supported": [
"string"
],
"tls_client_certificate_bound_access_tokens": true,
"token_endpoint_auth_signing_alg_values_supported": [
"string"
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | The OpenID Provider Configuration Metadata values | ResponseOpenIDProviderConfigMetadata |
Get JWKS
Code samples
GET https://<register-base-url>/cdr-register/v1/jwks HTTP/1.1
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json'
};
fetch('https://<register-base-url>/cdr-register/v1/jwks',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/jwks
JWKS endpoint containing the public keys used by the CDR Register to validate the signature of issued SSAs and authenticate outbound calls to participants in the CDR.
This endpoint does not require CORS.
Endpoint Version
Version | Versioning is not supported for this endpoint |
Example responses
200 Response
{
"keys": [
{
"alg": "string",
"e": "string",
"key_ops": [
"string"
],
"kid": "string",
"kty": "string",
"n": "string"
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | A JSON object that represents a set of JWKs | ResponseJWKS |
Get Data Holder Brands
Code samples
GET https://<register-base-url>/cdr-register/v1/{industry}/data-holders/brands HTTP/1.1
Accept: application/json
Authorization: string
x-v: string
x-min-v: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'Authorization':'string',
'x-v':'string',
'x-min-v':'string'
};
fetch('https://<register-base-url>/cdr-register/v1/{industry}/data-holders/brands',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/{industry}/data-holders/brands
Allows Data Recipients to discover Data Holder Brands available in the CDR ecosystem.
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
industry | path | string | mandatory | The industry the participant is retrieving data for (Banking, etc) |
Authorization | header | string | mandatory | An Authorisation Token as per [RFC6750]. |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The Register should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The Register should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. |
updated-since | query | string | optional | query filter returns results updated since the specified date-time |
page | query | PositiveInteger | optional | the page number to return |
page-size | query | PositiveInteger | optional | the number of records to return per page |
Enumerated Values
Parameter | Value |
---|---|
industry | banking |
industry | energy |
industry | telco |
industry | all |
Example responses
200 Response
{
"data": [
{
"dataHolderBrandId": "string",
"brandName": "string",
"industries": [
"banking"
],
"logoUri": "string",
"legalEntity": {
"legalEntityId": "string",
"legalEntityName": "string",
"logoUri": "string",
"registrationNumber": "string",
"registrationDate": "string",
"registeredCountry": "string",
"abn": "string",
"acn": "string",
"arbn": "string",
"anzsicDivision": "string",
"organisationType": "SOLE_TRADER",
"status": "ACTIVE"
},
"status": "ACTIVE",
"endpointDetail": {
"version": "string",
"publicBaseUri": "string",
"resourceBaseUri": "string",
"infosecBaseUri": "string",
"extensionBaseUri": "string",
"websiteUri": "string"
},
"authDetails": [
{
"registerUType": "SIGNED-JWT",
"jwksEndpoint": "string"
}
],
"lastUpdated": "string"
}
],
"links": {
"first": "string",
"last": "string",
"next": "string",
"prev": "string",
"self": "string"
},
"meta": {
"totalPages": 0,
"totalRecords": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseRegisterDataHolderBrandList |
400 | Bad Request | Missing Required Header / Invalid Version / Invalid Path Parameter | ResponseErrorListV2 |
401 | Unauthorized | Invalid Bearer Token | ResponseErrorListV2 |
406 | Not Acceptable | Unsupported Version | ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the CDR Register has responded with. |
Get Data Holder Brands Summary
Code samples
GET https://<register-base-url>/cdr-register/v1/{industry}/data-holders/brands/summary HTTP/1.1
Accept: application/json
x-v: string
x-min-v: string
If-None-Match: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'If-None-Match':'string'
};
fetch('https://<register-base-url>/cdr-register/v1/{industry}/data-holders/brands/summary',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/{industry}/data-holders/brands/summary
Endpoint used by participants to discover public details of Data Holder Brands from the CDR Register
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
industry | path | string | mandatory | The industry the participant is retrieving data for (Banking, etc) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The Register should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The Register should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. |
If-None-Match | header | string | optional | Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value. |
Enumerated Values
Parameter | Value |
---|---|
industry | banking |
industry | energy |
industry | telco |
industry | all |
Example responses
200 Response
{
"data": [
{
"dataHolderBrandId": "string",
"interimId": "string",
"brandName": "string",
"publicBaseUri": "string",
"logoUri": "string",
"industries": [
"banking"
],
"lastUpdated": "string",
"abn": "string",
"acn": "string",
"arbn": "string"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseDataHoldersBrandSummaryList |
304 | Not Modified | Not Modified - The current representation of the target resource matches with the entity-tag provided in the If-None-Match request header | None |
400 | Bad Request | Missing Required Header / Invalid Version / Invalid Path Parameter | ResponseErrorListV2 |
404 | Not Found | Industry Not Found | ResponseErrorListV2 |
406 | Not Acceptable | Unsupported Version | ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the CDR Register has responded with. | |
200 | Etag | string | Entity tag that uniquely represents the requested resource. | |
304 | Etag | string | Entity tag that uniquely represents the requested resource. |
Get Software Statement Assertion (SSA)
Code samples
GET https://<register-base-url>/cdr-register/v1/{industry}/data-recipients/brands/{dataRecipientBrandId}/software-products/{softwareProductId}/ssa HTTP/1.1
Accept: application/json
x-v: string
x-min-v: string
Authorization: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'Authorization':'string'
};
fetch('https://<register-base-url>/cdr-register/v1/{industry}/data-recipients/brands/{dataRecipientBrandId}/software-products/{softwareProductId}/ssa',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/{industry}/data-recipients/brands/{dataRecipientBrandId}/software-products/{softwareProductId}/ssa
Get a Software Statement Assertion (SSA) for a software product on the CDR Register to be used for Dynamic Client Registration with a Data Holder Brand.
Endpoint Version
Version | 3 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
industry | path | string | mandatory | The industry the participant is retrieving data for (Banking, etc) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The Register should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The Register should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. |
dataRecipientBrandId | path | string | mandatory | Unique id for the Accredited Data Recipient Brand that the Software Product is associated with in the CDR Register |
softwareProductId | path | string | mandatory | Unique id for the Accredited Data Recipient Software Product in the CDR Register |
Authorization | header | string | mandatory | An Authorisation Token as per [RFC6750]. |
Enumerated Values
Parameter | Value |
---|---|
industry | banking |
industry | energy |
industry | telco |
industry | all |
Example responses
200 Response
"string"
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | string |
400 | Bad Request | Missing Required Header / Invalid Version / Invalid Path Parameter | ResponseErrorListV2 |
401 | Unauthorized | Invalid Bearer Token | ResponseErrorListV2 |
403 | Forbidden | Invalid BrandId | ResponseErrorListV2 |
404 | Not Found | Invalid Software Product | ResponseErrorListV2 |
406 | Not Acceptable | Unsupported Version | ResponseErrorListV2 |
422 | Unprocessable Entity | SSA validation failed | ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the CDR Register has responded with. |
Get Data Holder Statuses
Code samples
GET https://<register-base-url>/cdr-register/v1/{industry}/data-holders/status HTTP/1.1
Accept: application/json
x-v: 1
x-min-v: string
If-None-Match: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'1',
'x-min-v':'string',
'If-None-Match':'string'
};
fetch('https://<register-base-url>/cdr-register/v1/{industry}/data-holders/status',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/{industry}/data-holders/status
Endpoint used by participants to discover the statuses for Data Holders from the CDR Register
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
industry | path | string | mandatory | The industry the participant is retrieving data for (Banking, etc) |
x-v | header | string | optional | The version of the API end point requested by the client. Must be set to a positive integer. For backwards compatiblity defaults to 1 if absent. Note that once version 1 is decommissioned the header will be mandatory for a valid response to be obtained |
x-min-v | header | string | optional | The minimum version of the API end point requested by the client. Must be set to a positive integer if provided. |
If-None-Match | header | string | optional | Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value. |
Enumerated Values
Parameter | Value |
---|---|
industry | banking |
industry | energy |
industry | telco |
industry | all |
Example responses
200 Response
{
"data": [
{
"legalEntityId": "string",
"status": "ACTIVE"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | DataHoldersStatusList |
304 | Not Modified | Not Modified - The current representation of the target resource matches with the entity-tag provided in the If-None-Match request header | None |
400 | Bad Request | Missing Required Header / Invalid Version / Invalid Path Parameter | ResponseErrorListV2 |
406 | Not Acceptable | Unsupported Version | ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the CDR Register has responded with. | |
200 | Etag | string | Entity tag that uniquely represents the requested resource. | |
304 | Etag | string | Entity tag that uniquely represents the requested resource. |
Get Software Products Statuses
Code samples
GET https://<register-base-url>/cdr-register/v1/{industry}/data-recipients/brands/software-products/status HTTP/1.1
Accept: application/json
x-v: string
x-min-v: string
If-None-Match: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'If-None-Match':'string'
};
fetch('https://<register-base-url>/cdr-register/v1/{industry}/data-recipients/brands/software-products/status',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/{industry}/data-recipients/brands/software-products/status
Endpoint used by participants to discover the statuses for software products from the CDR Register.
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
industry | path | string | mandatory | The industry the participant is retrieving data for (Banking, etc) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The Register should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The Register should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. |
If-None-Match | header | string | optional | Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value. |
Enumerated Values
Parameter | Value |
---|---|
industry | banking |
industry | energy |
industry | telco |
industry | all |
Example responses
200 Response
{
"data": [
{
"softwareProductId": "string",
"status": "ACTIVE"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | SoftwareProductsStatusList |
304 | Not Modified | Not Modified - The current representation of the target resource matches with the entity-tag provided in the If-None-Match request header | None |
400 | Bad Request | Missing Required Header / Invalid Version / Invalid Path Parameter | ResponseErrorListV2 |
406 | Not Acceptable | Unsupported Version | ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the CDR Register has responded with. | |
200 | Etag | string | Entity tag that uniquely represents the requested resource. | |
304 | Etag | string | Entity tag that uniquely represents the requested resource. |
Get Data Recipients Statuses
Code samples
GET https://<register-base-url>/cdr-register/v1/{industry}/data-recipients/status HTTP/1.1
Accept: application/json
x-v: string
x-min-v: string
If-None-Match: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'If-None-Match':'string'
};
fetch('https://<register-base-url>/cdr-register/v1/{industry}/data-recipients/status',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/{industry}/data-recipients/status
Endpoint used by participants to discover the statuses for Data Recipients from the CDR Register.
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
industry | path | string | mandatory | The industry the participant is retrieving data for (Banking, etc) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The Register should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The Register should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. |
If-None-Match | header | string | optional | Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value. |
Enumerated Values
Parameter | Value |
---|---|
industry | banking |
industry | energy |
industry | telco |
industry | all |
Example responses
200 Response
{
"data": [
{
"legalEntityId": "string",
"status": "ACTIVE"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | DataRecipientsStatusList |
304 | Not Modified | Not Modified - The current representation of the target resource matches with the entity-tag provided in the If-None-Match request header | None |
400 | Bad Request | Missing Required Header / Invalid Version / Invalid Path Parameter | ResponseErrorListV2 |
406 | Not Acceptable | Unsupported Version | ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the CDR Register has responded with. | |
200 | Etag | string | Entity tag that uniquely represents the requested resource. | |
304 | Etag | string | Entity tag that uniquely represents the requested resource. |
Get Data Recipients
Code samples
GET https://<register-base-url>/cdr-register/v1/{industry}/data-recipients HTTP/1.1
Accept: application/json
x-v: string
x-min-v: string
If-None-Match: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'If-None-Match':'string'
};
fetch('https://<register-base-url>/cdr-register/v1/{industry}/data-recipients',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /cdr-register/v1/{industry}/data-recipients
Endpoint used by participants to discover data recipients and associated brands and software products, available in the CDR ecosystem.
Obsolete versions: v2
Endpoint Version
Version | 3 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
industry | path | string | mandatory | The industry the participant is retrieving data for (Banking, etc) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The Register should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The Register should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the Register must respond with a 406 Not Acceptable. |
If-None-Match | header | string | optional | Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value. |
Enumerated Values
Parameter | Value |
---|---|
industry | banking |
industry | energy |
industry | telco |
industry | all |
Example responses
200 Response
{
"data": [
{
"legalEntityId": "string",
"legalEntityName": "string",
"accreditationNumber": "string",
"accreditationLevel": "UNRESTRICTED",
"logoUri": "string",
"dataRecipientBrands": [
{
"dataRecipientBrandId": "string",
"brandName": "string",
"logoUri": "string",
"softwareProducts": [
{
"softwareProductId": "string",
"softwareProductName": "string",
"softwareProductDescription": "string",
"logoUri": "string",
"status": "ACTIVE"
}
],
"status": "ACTIVE"
}
],
"status": "ACTIVE",
"lastUpdated": "string"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseRegisterDataRecipientList |
304 | Not Modified | Not Modified - The current representation of the target resource matches with the entity-tag provided in the If-None-Match request header | None |
400 | Bad Request | Missing Required Header / Invalid Version / Invalid Path Parameter | ResponseErrorListV2 |
406 | Not Acceptable | Unsupported Version | ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the CDR Register has responded with. | |
200 | Etag | string | Entity tag that uniquely represents the requested resource. | |
304 | Etag | string | Entity tag that uniquely represents the requested resource. |
Schemas
ResponseOpenIDProviderConfigMetadata
{
"issuer": "string",
"jwks_uri": "string",
"token_endpoint": "string",
"claims_supported": [
"string"
],
"id_token_signing_alg_values_supported": [
"string"
],
"subject_types_supported": [
"string"
],
"code_challenge_methods_supported": [
"string"
],
"scopes_supported": [
"string"
],
"response_types_supported": [
"string"
],
"grant_types_supported": [
"string"
],
"token_endpoint_auth_methods_supported": [
"string"
],
"tls_client_certificate_bound_access_tokens": true,
"token_endpoint_auth_signing_alg_values_supported": [
"string"
]
}
Response containing the Open ID Provider Configuration Metadata
Properties
Name | Type | Required | Description |
---|---|---|---|
issuer | URIString | mandatory | URL using the https scheme with no query or fragment component that the CDR Register asserts as its Issuer Identifier |
jwks_uri | URIString | mandatory | URL of the CDR Register's JSON Web Key Set [JWK] document. This contains the signing key(s) used to validate access tokens issued from the CDR Register. Note that this differs from the JWKS endpoint used to validate SSAs and CDR Register client authentication |
token_endpoint | URIString | mandatory | URL of the CDR Register's OAuth 2.0 Token Endpoint |
claims_supported | [string] | mandatory | JSON array containing a list of the Claim Names of the Claims that the CDR Register supplies values for |
id_token_signing_alg_values_supported | [string] | mandatory | JSON array containing a list of the JWS signing algorithms (alg values) supported by the CDR Register for the ID Token to encode the Claims in a JWT. Given the CDR Register does not issue ID tokens, this field can be safely ignored |
subject_types_supported | [string] | mandatory | JSON array containing a list of the Subject Identifier types that the CDR Register supports. Given the CDR Register does not issue ID tokens, this field can be safely ignored |
code_challenge_methods_supported | [string] | mandatory | JSON array containing a list of Proof Key for Code Exchange (PKCE) [RFC7636] code challenge methods supported by this authorization server. Given the CDR Register does not support PKCE, this field can be safely ignored |
scopes_supported | [string] | mandatory | JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that the CDR Register supports |
response_types_supported | [string] | mandatory | JSON array containing a list of the OAuth 2.0 response_type values that the CDR Registrer supports |
grant_types_supported | [string] | mandatory | JSON array containing a list of the OAuth 2.0 Grant Type values that the CDR Register supports |
token_endpoint_auth_methods_supported | [string] | mandatory | JSON array containing a list of Client Authentication methods supported by this Token Endpoint |
tls_client_certificate_bound_access_tokens | Boolean | mandatory | Boolean value indicating server support for mutual TLS client certificate bound access tokens |
token_endpoint_auth_signing_alg_values_supported | [string] | mandatory | JSON array containing a list of the JWS signing algorithms (alg values) supported by the token endpoint for the signature on the JWT [JWT] used to authenticate the client at the token endpoint for the "private_key_jwt" authentication method |
ResponseJWKS
{
"keys": [
{
"alg": "string",
"e": "string",
"key_ops": [
"string"
],
"kid": "string",
"kty": "string",
"n": "string"
}
]
}
Response containing the JSON Web Key Set
Properties
Name | Type | Required | Description |
---|---|---|---|
keys | [JWK] | mandatory | The value of the "keys" parameter is an array of JWK values |
JWK
{
"alg": "string",
"e": "string",
"key_ops": [
"string"
],
"kid": "string",
"kty": "string",
"n": "string"
}
Object representing a JSON Web Key
Properties
Name | Type | Required | Description |
---|---|---|---|
alg | ExternalRef | mandatory | The "alg" (algorithm) parameter identifies the algorithm intended for use with the key |
e | ExternalRef | mandatory | The "e" RSA public exponent parameter |
key_ops | [string] | mandatory | The "key_ops" (key operations) parameter identifies the operation(s) for which the key is intended to be used |
kid | ExternalRef | mandatory | The "kid" (key ID) parameter is partially used to match a specific key. Note the "kid" parameter is not guaranteed unique and additional parameters should be used to progressively to identify a key within a set |
kty | ExternalRef | mandatory | The "kty" (key type) parameter identifies the cryptographic algorithm family used with the key |
n | ExternalRef | mandatory | The "n" RSA public modulus parameter |
ResponseRegisterDataHolderBrandList
{
"data": [
{
"dataHolderBrandId": "string",
"brandName": "string",
"industries": [
"banking"
],
"logoUri": "string",
"legalEntity": {
"legalEntityId": "string",
"legalEntityName": "string",
"logoUri": "string",
"registrationNumber": "string",
"registrationDate": "string",
"registeredCountry": "string",
"abn": "string",
"acn": "string",
"arbn": "string",
"anzsicDivision": "string",
"organisationType": "SOLE_TRADER",
"status": "ACTIVE"
},
"status": "ACTIVE",
"endpointDetail": {
"version": "string",
"publicBaseUri": "string",
"resourceBaseUri": "string",
"infosecBaseUri": "string",
"extensionBaseUri": "string",
"websiteUri": "string"
},
"authDetails": [
{
"registerUType": "SIGNED-JWT",
"jwksEndpoint": "string"
}
],
"lastUpdated": "string"
}
],
"links": {
"first": "string",
"last": "string",
"next": "string",
"prev": "string",
"self": "string"
},
"meta": {
"totalPages": 0,
"totalRecords": 0
}
}
Response containing a list of CDR Register Data Holder Brand objects
Properties
Name | Type | Required | Description |
---|---|---|---|
data | [RegisterDataHolderBrand] | mandatory | Response data for the query |
links | LinksPaginated | mandatory | none |
meta | MetaPaginated | mandatory | none |
RegisterDataHolderBrand
{
"dataHolderBrandId": "string",
"brandName": "string",
"industries": [
"banking"
],
"logoUri": "string",
"legalEntity": {
"legalEntityId": "string",
"legalEntityName": "string",
"logoUri": "string",
"registrationNumber": "string",
"registrationDate": "string",
"registeredCountry": "string",
"abn": "string",
"acn": "string",
"arbn": "string",
"anzsicDivision": "string",
"organisationType": "SOLE_TRADER",
"status": "ACTIVE"
},
"status": "ACTIVE",
"endpointDetail": {
"version": "string",
"publicBaseUri": "string",
"resourceBaseUri": "string",
"infosecBaseUri": "string",
"extensionBaseUri": "string",
"websiteUri": "string"
},
"authDetails": [
{
"registerUType": "SIGNED-JWT",
"jwksEndpoint": "string"
}
],
"lastUpdated": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
dataHolderBrandId | string | mandatory | Unique id of the Data Holder Brand issued by the CDR Register |
brandName | string | mandatory | The name of Data Holder Brand |
industries | [Enum] | mandatory | The industries the Data Holder Brand belongs to |
logoUri | URIString | mandatory | Brand logo URI |
legalEntity | LegalEntityDetail | mandatory | The data that is common to all organisations, regardless of the type (e.g. company, trust, partnership, government) |
status | Enum | mandatory | none |
endpointDetail | RegisterDataHolderBrandServiceEndpoint | mandatory | Endpoints related to Data Holder Brand services |
authDetails | [RegisterDataHolderAuth] | mandatory | [Defines the mechanism used and associated endpoints for Data Holder to Data Recipient authentication] |
lastUpdated | DateTimeString | mandatory | The date/time that the Data Holder Brand data was last updated in the Register |
Enumerated Values
Property | Value |
---|---|
industries | banking |
industries | energy |
industries | telco |
status | ACTIVE |
status | INACTIVE |
status | REMOVED |
ResponseDataHoldersBrandSummaryList
{
"data": [
{
"dataHolderBrandId": "string",
"interimId": "string",
"brandName": "string",
"publicBaseUri": "string",
"logoUri": "string",
"industries": [
"banking"
],
"lastUpdated": "string",
"abn": "string",
"acn": "string",
"arbn": "string"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
data | [DataHolderBrandSummary] | mandatory | Response data for the query |
links | Links | mandatory | none |
meta | Meta | mandatory | none |
DataHolderBrandSummary
{
"dataHolderBrandId": "string",
"interimId": "string",
"brandName": "string",
"publicBaseUri": "string",
"logoUri": "string",
"industries": [
"banking"
],
"lastUpdated": "string",
"abn": "string",
"acn": "string",
"arbn": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
dataHolderBrandId | string | optional | Unique id of the Data Holder Brand issued by the CDR Register |
interimId | string | optional | Interim id of the Data Holder Brand issued by the CDR Register. This is to be used to uniquely identify the record when dataHolderBrandId is not populated and is not to be reused |
brandName | string | mandatory | The name of Data Holder Brand |
publicBaseUri | URIString | mandatory | Base URI for the Data Holder's Consumer Data Standard public endpoints |
logoUri | URIString | mandatory | Brand logo URI |
industries | [Enum] | mandatory | The industries the Data Holder Brand belongs to |
lastUpdated | DateTimeString | mandatory | The date/time that the Data Holder Brand data was last updated in the Register |
abn | string | optional | Australian Business Number for the organisation |
acn | string | optional | Australian Company Number for the organisation |
arbn | string | optional | Australian Registered Body Number. ARBNs are issued to registrable Australian bodies and foreign companies |
Enumerated Values
Property | Value |
---|---|
industries | banking |
industries | energy |
industries | telco |
DataHoldersStatusList
{
"data": [
{
"legalEntityId": "string",
"status": "ACTIVE"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
data | [DataHolderStatus] | mandatory | Response data for the query |
links | Links | mandatory | none |
meta | Meta | mandatory | none |
DataHolderStatus
{
"legalEntityId": "string",
"status": "ACTIVE"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
legalEntityId | string | mandatory | Unique id of the Data Holder Legal Entity issued by the CDR Register. |
status | Enum | mandatory | Data Holder status in the CDR Register |
Enumerated Values
Property | Value |
---|---|
status | ACTIVE |
status | REMOVED |
SoftwareProductsStatusList
{
"data": [
{
"softwareProductId": "string",
"status": "ACTIVE"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
data | [SoftwareProductStatus] | mandatory | Response data for the query |
links | Links | mandatory | none |
meta | Meta | mandatory | none |
SoftwareProductStatus
{
"softwareProductId": "string",
"status": "ACTIVE"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
softwareProductId | string | mandatory | Unique id of the software product issued by the CDR Register |
status | Enum | mandatory | Software product status in the CDR Register |
Enumerated Values
Property | Value |
---|---|
status | ACTIVE |
status | INACTIVE |
status | REMOVED |
DataRecipientsStatusList
{
"data": [
{
"legalEntityId": "string",
"status": "ACTIVE"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
data | [DataRecipientStatus] | mandatory | Response data for the query |
links | Links | mandatory | none |
meta | Meta | mandatory | none |
DataRecipientStatus
{
"legalEntityId": "string",
"status": "ACTIVE"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
legalEntityId | string | mandatory | Unique id of the Data Recipient Legal Entity issued by the CDR Register |
status | Enum | mandatory | Data Recipient status in the CDR Register |
Enumerated Values
Property | Value |
---|---|
status | ACTIVE |
status | SUSPENDED |
status | REVOKED |
status | SURRENDERED |
ResponseRegisterDataRecipientList
{
"data": [
{
"legalEntityId": "string",
"legalEntityName": "string",
"accreditationNumber": "string",
"accreditationLevel": "UNRESTRICTED",
"logoUri": "string",
"dataRecipientBrands": [
{
"dataRecipientBrandId": "string",
"brandName": "string",
"logoUri": "string",
"softwareProducts": [
{
"softwareProductId": "string",
"softwareProductName": "string",
"softwareProductDescription": "string",
"logoUri": "string",
"status": "ACTIVE"
}
],
"status": "ACTIVE"
}
],
"status": "ACTIVE",
"lastUpdated": "string"
}
],
"links": {
"self": "string"
},
"meta": {}
}
Response containing a list of Data Recipients in the CDR Register
Properties
Name | Type | Required | Description |
---|---|---|---|
data | [RegisterDataRecipient] | mandatory | Response data for the query |
links | Links | mandatory | none |
meta | Meta | mandatory | none |
RegisterDataRecipient
{
"legalEntityId": "string",
"legalEntityName": "string",
"accreditationNumber": "string",
"accreditationLevel": "UNRESTRICTED",
"logoUri": "string",
"dataRecipientBrands": [
{
"dataRecipientBrandId": "string",
"brandName": "string",
"logoUri": "string",
"softwareProducts": [
{
"softwareProductId": "string",
"softwareProductName": "string",
"softwareProductDescription": "string",
"logoUri": "string",
"status": "ACTIVE"
}
],
"status": "ACTIVE"
}
],
"status": "ACTIVE",
"lastUpdated": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
legalEntityId | string | mandatory | Unique id of the Data Recipient Legal Entity issued by the CDR Register. |
legalEntityName | string | mandatory | Legal name of the Data Recipient |
accreditationNumber | string | mandatory | CDR Register issued human readable unique number given to Data Recipients upon accreditation |
accreditationLevel | Enum | mandatory | Accreditation level of the Data Recipient in the CDR Register |
logoUri | URIString | mandatory | Legal Entity logo URI |
dataRecipientBrands | [DataRecipientBrandMetaData] | optional | [Metadata related to Data Recipient Brand] |
status | Enum | mandatory | Data Recipient status in the CDR Register |
lastUpdated | DateTimeString | mandatory | The date/time that the Legal Entity was last updated in the CDR Register |
Enumerated Values
Property | Value |
---|---|
accreditationLevel | UNRESTRICTED |
accreditationLevel | SPONSORED |
status | ACTIVE |
status | SUSPENDED |
status | REVOKED |
status | SURRENDERED |
DataRecipientBrandMetaData
{
"dataRecipientBrandId": "string",
"brandName": "string",
"logoUri": "string",
"softwareProducts": [
{
"softwareProductId": "string",
"softwareProductName": "string",
"softwareProductDescription": "string",
"logoUri": "string",
"status": "ACTIVE"
}
],
"status": "ACTIVE"
}
Metadata related to Data Recipient Brand
Properties
Name | Type | Required | Description |
---|---|---|---|
dataRecipientBrandId | string | mandatory | Unique id of the Data Recipient brand issued by the CDR Register |
brandName | string | mandatory | Data Recipient Brand name |
logoUri | URIString | mandatory | Data Recipient Brand logo URI |
softwareProducts | [SoftwareProductMetaData] | optional | [Data Recipient Brand Software Products] |
status | Enum | mandatory | Data Recipient Brand status in the CDR Register |
Enumerated Values
Property | Value |
---|---|
status | ACTIVE |
status | INACTIVE |
status | REMOVED |
SoftwareProductMetaData
{
"softwareProductId": "string",
"softwareProductName": "string",
"softwareProductDescription": "string",
"logoUri": "string",
"status": "ACTIVE"
}
Data Recipient Brand Software Products
Properties
Name | Type | Required | Description |
---|---|---|---|
softwareProductId | string | mandatory | Unique id of the Data Recipient software product issued by the CDR Register |
softwareProductName | string | mandatory | Name of the software product |
softwareProductDescription | string | mandatory | Description of the software product |
logoUri | URIString | mandatory | Software product logo URI |
status | Enum | mandatory | Software Product status in the CDR Register |
Enumerated Values
Property | Value |
---|---|
status | ACTIVE |
status | INACTIVE |
status | REMOVED |
LegalEntityDetail
{
"legalEntityId": "string",
"legalEntityName": "string",
"logoUri": "string",
"registrationNumber": "string",
"registrationDate": "string",
"registeredCountry": "string",
"abn": "string",
"acn": "string",
"arbn": "string",
"anzsicDivision": "string",
"organisationType": "SOLE_TRADER",
"status": "ACTIVE"
}
The data that is common to all organisations, regardless of the type (e.g. company, trust, partnership, government)
Properties
Name | Type | Required | Description |
---|---|---|---|
legalEntityId | string | mandatory | Unique id of the organisation issued by the CDR Register |
legalEntityName | string | mandatory | Unique legal name of the organisation |
logoUri | URIString | mandatory | Legal Entity logo URI |
registrationNumber | string | optional | Unique registration number (if the company is registered outside Australia) |
registrationDate | DateString | optional | Date of registration (if the company is registered outside Australia) |
registeredCountry | string | optional | Country of registration (if the company is registered outside Australia) |
abn | string | optional | Australian Business Number for the organisation |
acn | string | optional | Australian Company Number for the organisation |
arbn | string | optional | Australian Registered Body Number. ARBNs are issued to registrable Australian bodies and foreign companies |
anzsicDivision | ExternalRef | optional | ANZSIC division of the organisation. [ANZSIC-2006] |
organisationType | Enum | optional | Legal organisation type |
status | Enum | mandatory | none |
Enumerated Values
Property | Value |
---|---|
organisationType | SOLE_TRADER |
organisationType | COMPANY |
organisationType | PARTNERSHIP |
organisationType | TRUST |
organisationType | GOVERNMENT_ENTITY |
organisationType | OTHER |
status | ACTIVE |
status | REMOVED |
RegisterDataHolderBrandServiceEndpoint
{
"version": "string",
"publicBaseUri": "string",
"resourceBaseUri": "string",
"infosecBaseUri": "string",
"extensionBaseUri": "string",
"websiteUri": "string"
}
Endpoints related to Data Holder Brand services
Properties
Name | Type | Required | Description |
---|---|---|---|
version | string | mandatory | The major version of the high level standards. This is not the version of the endpoint or the payload being requested but the version of the overall standards being applied. This version number will be "v" followed by the major version of the standards as a positive integer (e.g. v1, v12 or v76) |
publicBaseUri | URIString | mandatory | Base URI for the Data Holder's Consumer Data Standard public endpoints |
resourceBaseUri | URIString | mandatory | Base URI for the Data Holder's Consumer Data Standard resource endpoints |
infosecBaseUri | URIString | mandatory | Base URI for the Data Holder's Consumer Data Standard information security endpoints |
extensionBaseUri | URIString | optional | Base URI for the Data Holder extension endpoints to the Consumer Data Standard (optional) |
websiteUri | URIString | mandatory | Publicly available website or web resource URI |
RegisterDataHolderAuth
{
"registerUType": "SIGNED-JWT",
"jwksEndpoint": "string"
}
Defines the mechanism used and associated endpoints for Data Holder to Data Recipient authentication
Properties
Name | Type | Required | Description |
---|---|---|---|
registerUType | Enum | mandatory | The type of authentication and authorisation mechanism in use |
jwksEndpoint | URIString | mandatory | JWKS endpoint used for authentication by the Data Holder with the Data Recipient |
Enumerated Values
Property | Value |
---|---|
registerUType | SIGNED-JWT |
LinksPaginated
{
"first": "string",
"last": "string",
"next": "string",
"prev": "string",
"self": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
first | URIString | optional | URI to the first page of this set. Mandatory if this response is not the first page |
last | URIString | optional | URI to the last page of this set. Mandatory if this response is not the last page |
next | URIString | optional | URI to the next page of this set. Mandatory if this response is not the last page |
prev | URIString | optional | URI to the previous page of this set. Mandatory if this response is not the first page |
self | URIString | mandatory | Fully qualified link to this API call |
MetaPaginated
{
"totalPages": 0,
"totalRecords": 0
}
Properties
Name | Type | Required | Description |
---|---|---|---|
totalPages | NaturalNumber | mandatory | The total number of pages in the full set |
totalRecords | NaturalNumber | mandatory | The total number of records in the full set |
Links
{
"self": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
self | URIString | mandatory | Fully qualified link to this API call |
Meta
{}
Properties
None
MetaError
{
"urn": "string"
}
Additional data for customised error codes
Properties
Name | Type | Required | Description |
---|---|---|---|
urn | string | conditional | The CDR error code URN which the application-specific error code extends. Mandatory if the error code is an application-specific error rather than a standardised error code. |
ResponseErrorListV2
{
"errors": [
{
"code": "string",
"title": "string",
"detail": "string",
"meta": {
"urn": "string"
}
}
]
}
Properties
Name | Type | Required | Description |
---|---|---|---|
errors | [ResponseErrorListV2_errors] | mandatory | none |
ResponseErrorListV2_errors
{
"code": "string",
"title": "string",
"detail": "string",
"meta": {
"urn": "string"
}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
code | string | mandatory | The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the meta object. Otherwise, the value is the error code URN. |
title | string | mandatory | A short, human-readable summary of the problem that MUST NOT change from occurrence to occurrence of the problem represented by the error code. |
detail | string | mandatory | A human-readable explanation specific to this occurrence of the problem. |
meta | MetaError | optional | Additional data for customised error codes |
Authorisation Scopes
The following authorisation scopes have been defined for the standards. Each API end point will specify which scopes are required to access the data available via that end point.
Public
Scope Name | Scope ID | Description |
---|---|---|
Public | NA | Openly accessible information. A customer would never need to grant this scope. This scope is included so that end points that can be called without requiring authorisation can be identified. Includes access to openly available information such as generic product information. |
OpenID Connect End-User Data
These scopes are used to access OpenID Connect scopes and individually requested claims of the authenticated End-User.
Scope Name | Scope ID | Description |
---|---|---|
Profile Data | profile | This scope would allow for the third party to access basic profile information of the authenticated End-User. Further details are provided in CX Data Language: Profile Scope section. |
CDR Data
These scopes are used to access authenticated resource endpoints that can be used to obtain CDR Data.
Scope Name | Scope ID | Description |
---|---|---|
Basic Bank Account Data | bank:accounts.basic:read | This scope would allow for the third party to access basic information of the customer’s accounts. Includes simple account information including balance. Does not include detailed account information such as account numbers, product information or transaction data. |
Detailed Bank Account Data | bank:accounts.detail:read | This scope would allow for the third party to access detailed information of the customer’s accounts. This scope is effectively additional authorisation to the Basic Bank Account Data scope. Granting this authorisation only makes sense if the Bank Account Data scope is also authorised. Includes basic account information plus account identifiers and product information. Does not include transaction data. |
Bank Transaction Data | bank:transactions:read | This scope would allow the third party to access transaction data for accounts. This scope is effectively additional authorisation to the Basic Bank Account Data scope. Granting this authorisation only makes sense if the Basic Bank Account Data scope is also authorised. Includes all account transaction data. |
Bank Payee Data | bank:payees:read | This scope allows access to payee information stored by the customer. Includes payee information such as billers, international beneficiaries and domestic payees. |
Bank Regular Payments | bank:regular_payments:read | The scope would allow the third party to access regular payments. Includes Direct Debits and Scheduled Payments. |
Basic Service Point Data | energy:electricity.servicepoints.basic:read | This scope would allow for the third party to access basic standing data information of the customer’s service points. Includes simple standing data including the National Meter Identifier (NMI). Does not include detailed service point information such as loaction or meter attributres. |
Detailed Service Point Data | energy:electricity.servicepoints.detail:read | This scope would allow for the third party to access detailed information of the customer’s service point connection. This scope is effectively additional authorisation to the Basic Service Point Data scope. Granting this authorisation only makes sense if the Service Point Data scope is also authorised. Includes basic service point information plus account identifiers and meter information. Does not include meter usage data. |
Electricity Usage Data | energy:electricity.usage:read | This scope would allow the third party to access electricity usage data for service points. This scope is effectively additional authorisation to the Basic Service Point Data scope. Granting this authorisation only makes sense if the Basic Service Point Data scope is also authorised. Includes all electricity usage data including basic and interval meter meters. |
Distributed Energy Resource Data | energy:electricity.der:read | This scope would allow the third party to access data about distributed energy resources for service points. This scope is effectively additional authorisation to the Basic Service Point Data scope. Granting this authorisation only makes sense if the Basic Service Point Data scope is also authorised. Includes distributed energy resource data available in AEMOs DER Register |
Basic Energy Account Data | energy:accounts.basic:read | This scope would allow for the third party to access basic information of the customer’s energy accounts with retailers. Includes simple energy account information basic plan information and service points that are part of the account. Does not include detailed account information such as tailored plans, electricity contract details or discounts. |
Detailed Energy Account Data | energy:accounts.detail:read | This scope would allow for the third party to access detailed information of the customer’s energy accounts with retailers. This scope is effectively additional authorisation to the Basic Energy Account Data scope. Granting this authorisation only makes sense if the Energy Account Data scope is also authorised. Includes basic energy account information plus tailored tariff information including charges included in the account or plan. Does not include usage data. |
Energy Regular Payments Data | energy:accounts.paymentschedule:read | The scope would allow the third party to access payment schedules for energy accounts. Includes Direct Debit or Credit based Scheduled Payments and Manual Payments. |
Energy Concession Data | energy:accounts.concessions:read | The scope would allow the third party to access the details of any concessions for a customer’s energy account. |
Energy Billing Data | energy:billing:read | The scope would allow the third party to access the billing and invoice data for a customer’s energy account. |
Basic Customer Data | common:customer.basic:read | The scope would allow the third party to access personally identifiable information about the customer. For retail customers this would be information about the customer themselves. For business customers it would imply the name of specific user but also information about the business. Includes name and occupation for individuals or name, business numbers and industry code for organisations |
Detailed Customer Data | common:customer.detail:read | The scope would allow the third party to access more detailed information about the customer. Includes the data available with the Basic Customer Data scope plus contact details. Includes basic data plus phone, email and address information. |
Admin & Registration
The following scopes are used for administrative interactions. These scopes MUST never be included in the same access token as a CDR Data scope.
Scope Name | Scope ID | Description |
---|---|---|
Basic Admin Metrics Data | admin:metrics.basic:read | Metrics data accessible ONLY to the CDR Register. If the Data Holder uses Private Key JWT Client Authentication to authenticate the CDR Register, this scope is required. Includes access to basic Metrics data. |
Admin Metadata Update Data | admin:metadata:update | Update notification accessible ONLY to the CDR Register. If the Data Holder uses Private Key JWT Client Authentication to authenticate the CDR Register, this scope is required. Includes permission to notify Data Holders of changes to Data Recipient metadata held by the CDR Register. |
Bank Participant Data | cdr-register:bank:read | This scope would allow Data Recipients and Data Holders access to participant metadata in the banking sector, held by the CDR Register. This scope is valid for the following endpoint versions:This scope is replaced by cdr-register:read for newer versions of these endpoints. |
Participant Data | cdr-register:read | This scope would allow Data Recipients and Data Holders access to participant metadata held by the CDR Register. Replaces cdr-register:bank:read for the following endpoint versions: |
Register Client | cdr:registration | This scope would allow a Data Recipient to register or manage a software product client with a Data Holder. |
Non-functional Requirements
The non-functional requirements (NFRs) for the Consumer Data Right regime cover a number of considerations:
- Minimum performance and availability expectations for data holders. Included to ensure a reliable and performant service is offered to Data Recipients and customers.
- Maximum traffic expectations for data holders. Included to ensure there is a ceiling for the amount of traffic that a data holder is expected to service.
- Requirements for reporting of performance. Included to provide transparency of performance without the need for time consuming auditing or inspection.
- Requirements for data latency and quality. Included to give a clear indication to the depth and recency of the data available under the regime.
- Limitations on the number of calls that a Data Recipient Software Product can make to a single provider. Included to protect data holders from poorly designed or overly transactional Data Recipient implementations.
Definitions
In the following definition of NFRs specific terms have the following meanings:
- Data Recipient Software Product: For the purposes of these NFRs a Data Recipient Software Product is defined, inline with the definition given in the CDR Federation, as a configured application presented in the register meta data. This acknowledges that a single accredited entity may be able to register multiple independent services (or apps) that can obtain authorisations from consumers independently of each other.
- Shared Responsibility Data Request: A request made to a secondary data holder by a Data Holder for designated data to fulfil a Consumer Data Request made by a Data Recipient Software Product.
- Session: A session is defined as the life span of a unique Access Token. Multiple API requests made with a single, valid, Access Token would be considered part of a single Session.
- Customer Present: Authenticated API requests made in direct response to interactions by the end customer using the digital services of the Data Recipient Software Product will be considered “Customer Present”. Technically a data holder will define an API request as “Customer Present” if, and only if, the
x-fapi-customer-ip-address
header is populated with a valid IP address of the end customer’s device. - Customer Not Present: Authenticated API requests that are not deemed to be “Customer Present”
- Unattended: A synonym of “Customer Not Present”
- Authenticated: API requests to API end points that the standards require to be protected by security mechanisms that enforce explicit customer authorisation
- Unauthenticated: API requests to API end points that the standards deem to be publicly available. This implies that these end points may be accessed by any client without the client performing any authentication or authorisation actions
- High Traffic Period: Any time in the 18 hour period between 6am and 12am (midnight) is considered to be a high traffic period
- Low Traffic Period: Any time of the day not considered to be included in a high traffic period.
- Large Payload: An API which is capable of returning a large data response that would reasonably impose higher data retrieval times on the resource server. Typically bulk request end points.
Session Requirements
The expiry time of a unique session should be set according to the statements included in the Security Profile.
After a unique session is expired it is expected that the Data Recipient Software Product, for the same customer, may establish a new session as long as the authorisation is still valid.
Availability Requirements
Service availability requirement for data holders and secondary data holders: 99.5% per month
The definition of a period of unavailability is any period of time when any of the API end points defined in the standard is unable to reliably provide a successful response to an appropriately constructed request.
The availability requirement applies to both authenticated and unauthenticated end points.
The availability requirement does not include planned outages. Planned outages should be:
- Commensurate in length and frequency to other primary digital channels offered by the data holder,
- Published to Data Recipient Software Products with at least one week lead time for normal outages,
- May occur without notification if the change is to resolve a critical service or security issue.
The unavailability of a secondary data holder will mean that some requests cannot be fulfilled by a data holder making a Shared Responsibility Data Request. This will not be taken to mean that the data holder is unavailable.
Performance Requirements
API end point performance will be measured in response time of individual API requests from receipt of request to delivery of response.
It is understood that different response times can be measured depending on which technical layer of an API implementation stack is instrumented and that not all of the technical layers between the Data Recipient Software Product and the Data Holder will be in the control of the Data Holder. As this is implementation specific it is expected that the Data Holder will ensure that the measurement of response time occurs as close to the Data Recipient Software Product as practicable.
In light of these considerations, the performance requirement for Data Holders is:
95% of calls per hour responded to within a nominated threshold
The nominated threshold for each end point will be according to the following table:
Tier | Response Time | Applies To… |
---|---|---|
Unauthenticated | 1500ms | All Unauthenticated end points not otherwise specified in a separate threshold. |
High Priority | 1000ms | All calls to the following end points:
Energy Common |
Low Priority | 1500ms | Customer Present calls to the following end points:
Energy |
Unattended | 4000ms | Unattended calls to the following end points:
Energy Common Admin |
Large Payload | 6000ms | Any calls to the following end points:
Energy |
Secondary Request | 1000ms (for data holders) 1500ms (for secondary data holders) |
Customer Present calls to the following end points:
|
Large Secondary Request | 1500ms (for data holders) 4500ms (for secondary data holders) |
Unattended calls to the following end points:
|
Note that calls initiated in excess of a traffic threshold (see next section) may be excluded from the performance requirement.
Traffic Thresholds
Calls in excess of the following traffic thresholds will be able to be freely throttled or rejected by a data holder without impact to their performance or availability requirements.
Traffic thresholds will be set using the following metrics:
- Number of sessions per day – the number of individual sessions initiated in a calendar day.
- Transactions Per Second (TPS) – the number of concurrent transactions each second.
- Number of calls – the number of end point calls initiated for a specified duration.
For Customer Present and authorisation traffic the following traffic thresholds will apply:
- Unlimited sessions per day
- 10 TPS per customer
- 50 TPS per Data Recipient Software Product
For Unattended traffic the following traffic thresholds will apply for low traffic periods:
- 20 sessions per day, per customer, per Data Recipient Software Product
- 100 total calls per session
- 5TPS per session
- 50 TPS per Data Recipient Software Product
For Unattended traffic during high traffic periods only best effort support is required.
For secure traffic (both Customer Present and Unattended) the following traffic thresholds will apply:
- For Data Holders with 0 to 10,000 active authorisations, 150 peak TPS total across all consumers
- For Data Holders with 10,001 to 20,000 active authorisations, 200 peak TPS total across all consumers
- For Data Holders with 20,001 to 30,000 active authorisations, 250 peak TPS total across all consumers
- For Data Holders with 30,001 to 40,000 active authorisations, 300 peak TPS total across all consumers
- For Data Holders with 40,001 to 50,000 active authorisations, 350 peak TPS total across all consumers
- For Data Holders with 50,001 to 60,000 active authorisations, 400 peak TPS total across all consumers
- For Data Holders with more than 60,000 active authorisations, 450 peak TPS total across all consumers
For Public traffic (i.e. traffic to unauthenticated end points) the following traffic thresholds will apply:
- 300 TPS total across all consumers (additive to secure traffic)
As traffic from Data Recipient Software Products to Data Holders will be shaped by the thresholds above, there are no specific thresholds applicable to secondary Data Holders.
Data Recipient Requirements
Data Recipient Software Products will be limited by the traffic thresholds documented in the previous section. In addition to this Data Recipients are expected to design their services according to the following principles:
- Services should be designed to minimise traffic with Data Holders
- Services should be designed to be resilient in the case of the rejection of a call by a Data Holder due to traffic threshold breaches
- Services should schedule unattended calls to avoid high traffic periods
- Unattended calls should be managed to avoid short term bursts of traffic
Low Velocity Data Sets
For endpoints that provide access to data that is low velocity (ie. the data does not change frequently) the Data Recipient Software Product is expected to cache the results of any data they receive and not request the same resource again until the data may reasonably have changed.
For low velocity data sets, if the same data is requested repeatedly a Data Holder may reject subsequent requests for the same data during a specified period.
Identified low velocity data sets are to be handled according to the following table noting that:
- the Velocity Time Period is a continuous period of time in which calls beyond a specific threshold MAY be rejected by the Data Holder
- the Allowable Call Volume is the threshold number of calls to the same resource for the same arrangement above which calls MAY be rejected by the Data Holder
Data Set | Impacted Endpoints | Velocity Time Period | Allowable Call Volume |
---|---|---|---|
NMI Standing Data | Get Service Point Detail | 24 hours | 10 calls |
Energy Usage Data | Get Usage For Service Point, Get Bulk Usage, Get Usage For Specific Service Points | 24 hours | 10 calls |
DER Data | Get DER For Service Point, Get Bulk DER, Get DER For Specific Service Points | 24 hours | 10 calls |
Reporting Requirements
The mechanism for reporting will be via the CDR Administration Endpoints.
The following information is to be reported:
- Availability for current month
- Availability for each of the previous twelve months
- Percentage of calls within performance threshold for current day
- Percentage of calls within performance threshold for each of the previous seven days
- Number of calls within each performance tier for current day
- Number of calls within each performance tier for each of the previous seven days
- Average response time within each performance tier for current day
- Average response time within each performance tier for each of the previous seven days
- Number of sessions for current day
- Number of sessions for each of the previous seven days
- Peak total TPS for current day
- Peak total TPS for each of the previous seven days
- Average TPS for current day
- Average TPS for each of the previous seven days
- Number of calls resulting in error due to server execution for current day
- Number of calls resulting in error due to server execution for each of the previous seven days
- Number of calls rejected due to traffic thresholds for current day
- Number of calls rejected due to traffic thresholds for each of the previous seven days
- Number of customers with active authorisations
- Number of Data Recipient Software Products with active authorisations
Data Latency
Within this proposal there is no specific requirement with regard to data latency (ie. how up to date data should be). Instead, the requirement for data latency is that data presented via API end points should be commensurate to data presented via other primary digital channels.
For example, for a Bank that provides a mobile application as their primary digital experience, a balance presented via one of the balance end points should be the same as the balance presented through the mobile application.
To be able to manage network efficiency using normal mechanisms, a data holder making Shared Responsibility Data Requests may cache the results from the secondary data holder for a short period of time to accommodate repeated, duplicate, calls from the Data Recipient Software Product. Any such cache should be short lived.
Data Quality
If a Data Holder of CDR data is required or authorised under the Consumer Data Rules to disclose product data, the Data Holder must take reasonable steps to ensure that the product data is, having regard to the purpose for which it is held, accurate, up to date and complete.
Data Holders are required to be able to demonstrate that reasonable steps to maintain data quality of product data are being undertaken.
Note: For the data quality requirements that apply to CDR data for which there are one or more CDR consumers, see Privacy Safeguard 11 (section 56EN of the Competition and Consumer Act 2010). There are requirements in Privacy Safeguard 11 for both Data Holders and Data Recipients. See Chapter 11 (Privacy Safeguard 11) of the OAIC’s CDR Privacy Safeguard Guidelines for further information.
Exemptions To Protect Service
In the event of the following extreme circumstances data holders will be able to obtain relief from non-functional requirements:
- Periods of time when the digital channels for the data holder are the target for a distributed denial of service or equivalent form of attack (this should result in http error
429 Too Many Requests
being returned). - A significant increase in traffic from a poorly designed or misbehaving Data Recipient Software Product (this should result in http error
429 Too Many Requests
being returned). - If the data holder identifies a situation where there is the potential for physical or financial harm or abuse (this should result in http error
403 Forbidden
being returned).
Banking APIs
This specification defines the APIs for Data Holders exposing Banking endpoints.
Banking OpenAPI Specification (JSON) |
Banking OpenAPI Specification (YAML) |
Get Accounts
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts
Obtain a list of accounts.
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
product-category | query | string | optional | Used to filter results on the productCategory field applicable to accounts. Any one of the valid values for this field can be supplied. If absent then all accounts returned.) |
open-status | query | string | optional | Used to filter results according to open/closed status. Values can be OPEN, CLOSED or ALL. If absent then ALL is assumed |
is-owned | query | Boolean | optional | Filters accounts based on whether they are owned by the authorised customer. True for owned accounts, false for unowned accounts and absent for all accounts |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Enumerated Values
Parameter | Value |
---|---|
product-category | BUSINESS_LOANS |
product-category | CRED_AND_CHRG_CARDS |
product-category | LEASES |
product-category | MARGIN_LOANS |
product-category | OVERDRAFTS |
product-category | PERS_LOANS |
product-category | REGULATED_TRUST_ACCOUNTS |
product-category | RESIDENTIAL_MORTGAGES |
product-category | TERM_DEPOSITS |
product-category | TRADE_FINANCE |
product-category | TRANS_AND_SAVINGS_ACCOUNTS |
product-category | TRAVEL_CARDS |
open-status | ALL |
open-status | CLOSED |
open-status | OPEN |
Example responses
200 Response
{
"data": {
"accounts": [
{
"accountId": "string",
"creationDate": "string",
"displayName": "string",
"nickname": "string",
"openStatus": "CLOSED",
"isOwned": true,
"accountOwnership": "UNKNOWN",
"maskedNumber": "string",
"productCategory": "BUSINESS_LOANS",
"productName": "string"
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingAccountListV2 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Bulk Balances
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/balances HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/balances',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/balances
Obtain balances for multiple, filtered accounts
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
product-category | query | string | optional | Used to filter results on the productCategory field applicable to accounts. Any one of the valid values for this field can be supplied. If absent then all accounts returned. |
open-status | query | string | optional | Used to filter results according to open/closed status. Values can be OPEN, CLOSED or ALL. If absent then ALL is assumed |
is-owned | query | Boolean | optional | Filters accounts based on whether they are owned by the authorised customer. True for owned accounts, false for unowned accounts and absent for all accounts |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Enumerated Values
Parameter | Value |
---|---|
product-category | BUSINESS_LOANS |
product-category | CRED_AND_CHRG_CARDS |
product-category | LEASES |
product-category | MARGIN_LOANS |
product-category | OVERDRAFTS |
product-category | PERS_LOANS |
product-category | REGULATED_TRUST_ACCOUNTS |
product-category | RESIDENTIAL_MORTGAGES |
product-category | TERM_DEPOSITS |
product-category | TRADE_FINANCE |
product-category | TRANS_AND_SAVINGS_ACCOUNTS |
product-category | TRAVEL_CARDS |
open-status | ALL |
open-status | CLOSED |
open-status | OPEN |
Example responses
200 Response
{
"data": {
"balances": [
{
"accountId": "string",
"currentBalance": "string",
"availableBalance": "string",
"creditLimit": "string",
"amortisedLimit": "string",
"currency": "string",
"purses": [
{
"amount": "string",
"currency": "string"
}
]
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingAccountsBalanceList |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Balances For Specific Accounts
Code samples
POST https://data.holder.com.au/cds-au/v1/banking/accounts/balances HTTP/1.1
Host: data.holder.com.au
Content-Type: application/json
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const inputBody = '{
"data": {
"accountIds": [
"string"
]
},
"meta": {}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/balances',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
POST /banking/accounts/balances
Obtain balances for a specified list of accounts
Body parameter
{
"data": {
"accountIds": [
"string"
]
},
"meta": {}
}
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
body | body | RequestAccountIds | mandatory | The list of account IDs to obtain balances for |
Example responses
200 Response
{
"data": {
"balances": [
{
"accountId": "string",
"currentBalance": "string",
"availableBalance": "string",
"creditLimit": "string",
"amortisedLimit": "string",
"currency": "string",
"purses": [
{
"amount": "string",
"currency": "string"
}
]
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingAccountsBalanceList |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Account Balance
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/balance HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/balance',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/{accountId}/balance
Obtain the balance for a single specified account
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountId | path | ASCIIString | mandatory | ID of the specific account requested |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Example responses
200 Response
{
"data": {
"accountId": "string",
"currentBalance": "string",
"availableBalance": "string",
"creditLimit": "string",
"amortisedLimit": "string",
"currency": "string",
"purses": [
{
"amount": "string",
"currency": "string"
}
]
},
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingAccountsBalanceById |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
404 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Account Detail
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId} HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/{accountId}
Obtain detailed information on a single account.
Endpoint Version
Version | 3 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountId | path | ASCIIString | mandatory | A tokenised identifier for the account which is unique but not shareable |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Example responses
200 Response
{
"data": {
"accountId": "string",
"creationDate": "string",
"displayName": "string",
"nickname": "string",
"openStatus": "CLOSED",
"isOwned": true,
"accountOwnership": "UNKNOWN",
"maskedNumber": "string",
"productCategory": "BUSINESS_LOANS",
"productName": "string",
"bsb": "string",
"accountNumber": "string",
"bundleName": "string",
"specificAccountUType": "creditCard",
"termDeposit": [
{
"lodgementDate": "string",
"maturityDate": "string",
"maturityAmount": "string",
"maturityCurrency": "string",
"maturityInstructions": "HOLD_ON_MATURITY"
}
],
"creditCard": {
"minPaymentAmount": "string",
"paymentDueAmount": "string",
"paymentCurrency": "string",
"paymentDueDate": "string"
},
"loan": {
"originalStartDate": "string",
"originalLoanAmount": "string",
"originalLoanCurrency": "string",
"loanEndDate": "string",
"nextInstalmentDate": "string",
"minInstalmentAmount": "string",
"minInstalmentCurrency": "string",
"maxRedraw": "string",
"maxRedrawCurrency": "string",
"minRedraw": "string",
"minRedrawCurrency": "string",
"offsetAccountEnabled": true,
"offsetAccountIds": [
"string"
],
"repaymentType": "INTEREST_ONLY",
"repaymentFrequency": "string"
},
"depositRate": "string",
"lendingRate": "string",
"depositRates": [
{
"depositRateType": "BONUS",
"rate": "string",
"calculationFrequency": "string",
"applicationFrequency": "string",
"tiers": [
{
"name": "string",
"unitOfMeasure": "DAY",
"minimumValue": 0,
"maximumValue": 0,
"rateApplicationMethod": "PER_TIER",
"applicabilityConditions": {
"additionalInfo": "string",
"additionalInfoUri": "string"
},
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"lendingRates": [
{
"lendingRateType": "BUNDLE_DISCOUNT_FIXED",
"rate": "string",
"comparisonRate": "string",
"calculationFrequency": "string",
"applicationFrequency": "string",
"interestPaymentDue": "IN_ADVANCE",
"repaymentType": "INTEREST_ONLY",
"loanPurpose": "INVESTMENT",
"tiers": [
{
"name": "string",
"unitOfMeasure": "DAY",
"minimumValue": 0,
"maximumValue": 0,
"rateApplicationMethod": "PER_TIER",
"applicabilityConditions": {
"additionalInfo": "string",
"additionalInfoUri": "string"
},
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"features": [
{
"featureType": "ADDITIONAL_CARDS",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string",
"isActivated": true
}
],
"fees": [
{
"name": "string",
"feeType": "DEPOSIT",
"amount": "string",
"balanceRate": "string",
"transactionRate": "string",
"accruedRate": "string",
"accrualFrequency": "string",
"currency": "string",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string",
"discounts": [
{
"description": "string",
"discountType": "BALANCE",
"amount": "string",
"balanceRate": "string",
"transactionRate": "string",
"accruedRate": "string",
"feeRate": "string",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string",
"eligibility": [
{
"discountEligibilityType": "BUSINESS",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
]
}
]
}
],
"addresses": [
{
"addressUType": "paf",
"simple": {
"mailingName": "string",
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"postcode": "string",
"city": "string",
"state": "string",
"country": "AUS"
},
"paf": {
"dpid": "string",
"thoroughfareNumber1": 0,
"thoroughfareNumber1Suffix": "string",
"thoroughfareNumber2": 0,
"thoroughfareNumber2Suffix": "string",
"flatUnitType": "string",
"flatUnitNumber": "string",
"floorLevelType": "string",
"floorLevelNumber": "string",
"lotNumber": "string",
"buildingName1": "string",
"buildingName2": "string",
"streetName": "string",
"streetType": "string",
"streetSuffix": "string",
"postalDeliveryType": "string",
"postalDeliveryNumber": 0,
"postalDeliveryNumberPrefix": "string",
"postalDeliveryNumberSuffix": "string",
"localityName": "string",
"postcode": "string",
"state": "string"
}
}
]
},
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingAccountByIdV3 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
404 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Transactions For Account
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/transactions HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/transactions',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/{accountId}/transactions
Obtain transactions for a specific account.
Some general notes that apply to all end points that retrieve transactions:
- Where multiple transactions are returned, transactions should be ordered according to effective date in descending order
- As the date and time for a transaction can alter depending on status and transaction type two separate date/times are included in the payload. There are still some scenarios where neither of these time stamps is available. For the purpose of filtering and ordering it is expected that the data holder will use the "effective" date/time which will be defined as:
- Posted date/time if available, then
- Execution date/time if available, then
- A reasonable date/time nominated by the data holder using internal data structures
- For transaction amounts it should be assumed that a negative value indicates a reduction of the available balance on the account while a positive value indicates an increase in the available balance on the account
- For aggregated transactions (ie. groups of sub transactions reported as a single entry for the account) only the aggregated information, with as much consistent information across the subsidiary transactions as possible, is required to be shared
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountId | path | ASCIIString | mandatory | ID of the account to get transactions for. Must have previously been returned by one of the account list end points. |
oldest-time | query | DateTimeString | optional | Constrain the transaction history request to transactions with effective time at or after this date/time. If absent defaults to newest-time minus 90 days. Format is aligned to DateTimeString common type |
newest-time | query | DateTimeString | optional | Constrain the transaction history request to transactions with effective time at or before this date/time. If absent defaults to today. Format is aligned to DateTimeString common type |
min-amount | query | AmountString | optional | Filter transactions to only transactions with amounts higher than or equal to this amount |
max-amount | query | AmountString | optional | Filter transactions to only transactions with amounts less than or equal to this amount |
text | query | string | optional | Filter transactions to only transactions where this string value is found as a substring of either the reference or description fields. Format is arbitrary ASCII string. This parameter is optionally implemented by data holders. If it is not implemented then a response should be provided as normal without text filtering applied and an additional boolean field named isQueryParamUnsupported should be included in the meta object and set to true (whether the text parameter is supplied or not) |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Example responses
200 Response
{
"data": {
"transactions": [
{
"accountId": "string",
"transactionId": "string",
"isDetailAvailable": true,
"type": "DIRECT_DEBIT",
"status": "PENDING",
"description": "string",
"postingDateTime": "string",
"valueDateTime": "string",
"executionDateTime": "string",
"amount": "string",
"currency": "string",
"reference": "string",
"merchantName": "string",
"merchantCategoryCode": "string",
"billerCode": "string",
"billerName": "string",
"crn": "string",
"apcaNumber": "string"
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0,
"isQueryParamUnsupported": false
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingTransactionList |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
404 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Transaction Detail
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/transactions/{transactionId} HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/transactions/{transactionId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/{accountId}/transactions/{transactionId}
Obtain detailed information on a transaction for a specific account
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountId | path | ASCIIString | mandatory | ID of the account to get transactions for. Must have previously been returned by one of the account list end points |
transactionId | path | ASCIIString | mandatory | ID of the transaction obtained from a previous call to one of the other transaction end points |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Example responses
200 Response
{
"data": {
"accountId": "string",
"transactionId": "string",
"isDetailAvailable": true,
"type": "DIRECT_DEBIT",
"status": "PENDING",
"description": "string",
"postingDateTime": "string",
"valueDateTime": "string",
"executionDateTime": "string",
"amount": "string",
"currency": "string",
"reference": "string",
"merchantName": "string",
"merchantCategoryCode": "string",
"billerCode": "string",
"billerName": "string",
"crn": "string",
"apcaNumber": "string",
"extendedData": {
"payer": "string",
"payee": "string",
"extensionUType": "x2p101Payload",
"x2p101Payload": {
"extendedDescription": "string",
"endToEndId": "string",
"purposeCode": "string"
},
"service": "X2P1.01"
}
},
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingTransactionById |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
404 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Direct Debits For Account
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/direct-debits HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/direct-debits',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/{accountId}/direct-debits
Obtain direct debit authorisations for a specific account
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountId | path | ASCIIString | mandatory | ID of the account to get direct debit authorisations for. Must have previously been returned by one of the account list end points. |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Example responses
200 Response
{
"data": {
"directDebitAuthorisations": [
{
"accountId": "string",
"authorisedEntity": {
"description": "string",
"financialInstitution": "string",
"abn": "string",
"acn": "string",
"arbn": "string"
},
"lastDebitDateTime": "string",
"lastDebitAmount": "string"
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingDirectDebitAuthorisationList |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
404 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Bulk Direct Debits
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/direct-debits HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/direct-debits',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/direct-debits
Obtain direct debit authorisations for multiple, filtered accounts
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
product-category | query | string | optional | Used to filter results on the productCategory field applicable to accounts. Any one of the valid values for this field can be supplied. If absent then all accounts returned. |
open-status | query | string | optional | Used to filter results according to open/closed status. Values can be OPEN, CLOSED or ALL. If absent then ALL is assumed |
is-owned | query | Boolean | optional | Filters accounts based on whether they are owned by the authorised customer. True for owned accounts, false for unowned accounts and absent for all accounts |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Enumerated Values
Parameter | Value |
---|---|
product-category | BUSINESS_LOANS |
product-category | CRED_AND_CHRG_CARDS |
product-category | LEASES |
product-category | MARGIN_LOANS |
product-category | OVERDRAFTS |
product-category | PERS_LOANS |
product-category | REGULATED_TRUST_ACCOUNTS |
product-category | RESIDENTIAL_MORTGAGES |
product-category | TERM_DEPOSITS |
product-category | TRADE_FINANCE |
product-category | TRANS_AND_SAVINGS_ACCOUNTS |
product-category | TRAVEL_CARDS |
open-status | ALL |
open-status | CLOSED |
open-status | OPEN |
Example responses
200 Response
{
"data": {
"directDebitAuthorisations": [
{
"accountId": "string",
"authorisedEntity": {
"description": "string",
"financialInstitution": "string",
"abn": "string",
"acn": "string",
"arbn": "string"
},
"lastDebitDateTime": "string",
"lastDebitAmount": "string"
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingDirectDebitAuthorisationList |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Direct Debits For Specific Accounts
Code samples
POST https://data.holder.com.au/cds-au/v1/banking/accounts/direct-debits HTTP/1.1
Host: data.holder.com.au
Content-Type: application/json
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const inputBody = '{
"data": {
"accountIds": [
"string"
]
},
"meta": {}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/direct-debits',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
POST /banking/accounts/direct-debits
Obtain direct debit authorisations for a specified list of accounts
Body parameter
{
"data": {
"accountIds": [
"string"
]
},
"meta": {}
}
Endpoint Version
Version | 1 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
body | body | RequestAccountIds | mandatory | Array of specific accountIds to obtain authorisations for |
Example responses
200 Response
{
"data": {
"directDebitAuthorisations": [
{
"accountId": "string",
"authorisedEntity": {
"description": "string",
"financialInstitution": "string",
"abn": "string",
"acn": "string",
"arbn": "string"
},
"lastDebitDateTime": "string",
"lastDebitAmount": "string"
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingDirectDebitAuthorisationList |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Scheduled Payments for Account
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/payments/scheduled HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/accounts/{accountId}/payments/scheduled',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/accounts/{accountId}/payments/scheduled
Obtain scheduled, outgoing payments for a specific account
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
accountId | path | ASCIIString | mandatory | ID of the account to get scheduled payments for. Must have previously been returned by one of the account list end points. The account specified is the source account for the payment |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Example responses
200 Response
{
"data": {
"scheduledPayments": [
{
"scheduledPaymentId": "string",
"nickname": "string",
"payerReference": "string",
"payeeReference": "string",
"status": "ACTIVE",
"from": {
"accountId": "string"
},
"paymentSet": [
{
"to": {
"toUType": "accountId",
"accountId": "string",
"payeeId": "string",
"nickname": "string",
"payeeReference": "string",
"digitalWallet": {
"name": "string",
"identifier": "string",
"type": "EMAIL",
"provider": "PAYPAL_AU"
},
"domestic": {
"payeeAccountUType": "account",
"account": {
"accountName": "string",
"bsb": "string",
"accountNumber": "string"
},
"card": {
"cardNumber": "string"
},
"payId": {
"name": "string",
"identifier": "string",
"type": "ABN"
}
},
"biller": {
"billerCode": "string",
"crn": "string",
"billerName": "string"
},
"international": {
"beneficiaryDetails": {
"name": "string",
"country": "string",
"message": "string"
},
"bankDetails": {
"country": "string",
"accountNumber": "string",
"bankAddress": {
"name": "string",
"address": "string"
},
"beneficiaryBankBIC": "string",
"fedWireNumber": "string",
"sortCode": "string",
"chipNumber": "string",
"routingNumber": "string",
"legalEntityIdentifier": "string"
}
}
},
"isAmountCalculated": true,
"amount": "string",
"currency": "string"
}
],
"recurrence": {
"nextPaymentDate": "string",
"recurrenceUType": "eventBased",
"onceOff": {
"paymentDate": "string"
},
"intervalSchedule": {
"finalPaymentDate": "string",
"paymentsRemaining": 1,
"nonBusinessDayTreatment": "AFTER",
"intervals": [
{
"interval": "string",
"dayInInterval": "string"
}
]
},
"lastWeekDay": {
"finalPaymentDate": "string",
"paymentsRemaining": 1,
"interval": "string",
"lastWeekDay": "FRI",
"nonBusinessDayTreatment": "AFTER"
},
"eventBased": {
"description": "string"
}
}
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingScheduledPaymentsListV2 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
404 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Scheduled Payments Bulk
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/payments/scheduled HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/payments/scheduled',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/payments/scheduled
Obtain scheduled payments for multiple, filtered accounts that are the source of funds for the payments
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
product-category | query | string | optional | Used to filter results on the productCategory field applicable to accounts. Any one of the valid values for this field can be supplied. If absent then all accounts returned. |
open-status | query | string | optional | Used to filter results according to open/closed status. Values can be OPEN, CLOSED or ALL. If absent then ALL is assumed |
is-owned | query | Boolean | optional | Filters accounts based on whether they are owned by the authorised customer. True for owned accounts, false for unowned accounts and absent for all accounts |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Enumerated Values
Parameter | Value |
---|---|
product-category | BUSINESS_LOANS |
product-category | CRED_AND_CHRG_CARDS |
product-category | LEASES |
product-category | MARGIN_LOANS |
product-category | OVERDRAFTS |
product-category | PERS_LOANS |
product-category | REGULATED_TRUST_ACCOUNTS |
product-category | RESIDENTIAL_MORTGAGES |
product-category | TERM_DEPOSITS |
product-category | TRADE_FINANCE |
product-category | TRANS_AND_SAVINGS_ACCOUNTS |
product-category | TRAVEL_CARDS |
open-status | ALL |
open-status | CLOSED |
open-status | OPEN |
Example responses
200 Response
{
"data": {
"scheduledPayments": [
{
"scheduledPaymentId": "string",
"nickname": "string",
"payerReference": "string",
"payeeReference": "string",
"status": "ACTIVE",
"from": {
"accountId": "string"
},
"paymentSet": [
{
"to": {
"toUType": "accountId",
"accountId": "string",
"payeeId": "string",
"nickname": "string",
"payeeReference": "string",
"digitalWallet": {
"name": "string",
"identifier": "string",
"type": "EMAIL",
"provider": "PAYPAL_AU"
},
"domestic": {
"payeeAccountUType": "account",
"account": {
"accountName": "string",
"bsb": "string",
"accountNumber": "string"
},
"card": {
"cardNumber": "string"
},
"payId": {
"name": "string",
"identifier": "string",
"type": "ABN"
}
},
"biller": {
"billerCode": "string",
"crn": "string",
"billerName": "string"
},
"international": {
"beneficiaryDetails": {
"name": "string",
"country": "string",
"message": "string"
},
"bankDetails": {
"country": "string",
"accountNumber": "string",
"bankAddress": {
"name": "string",
"address": "string"
},
"beneficiaryBankBIC": "string",
"fedWireNumber": "string",
"sortCode": "string",
"chipNumber": "string",
"routingNumber": "string",
"legalEntityIdentifier": "string"
}
}
},
"isAmountCalculated": true,
"amount": "string",
"currency": "string"
}
],
"recurrence": {
"nextPaymentDate": "string",
"recurrenceUType": "eventBased",
"onceOff": {
"paymentDate": "string"
},
"intervalSchedule": {
"finalPaymentDate": "string",
"paymentsRemaining": 1,
"nonBusinessDayTreatment": "AFTER",
"intervals": [
{
"interval": "string",
"dayInInterval": "string"
}
]
},
"lastWeekDay": {
"finalPaymentDate": "string",
"paymentsRemaining": 1,
"interval": "string",
"lastWeekDay": "FRI",
"nonBusinessDayTreatment": "AFTER"
},
"eventBased": {
"description": "string"
}
}
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingScheduledPaymentsListV2 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Scheduled Payments For Specific Accounts
Code samples
POST https://data.holder.com.au/cds-au/v1/banking/payments/scheduled HTTP/1.1
Host: data.holder.com.au
Content-Type: application/json
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const inputBody = '{
"data": {
"accountIds": [
"string"
]
},
"meta": {}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/payments/scheduled',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
POST /banking/payments/scheduled
Obtain scheduled payments for a specified list of accounts
Obsolete versions: v1
Body parameter
{
"data": {
"accountIds": [
"string"
]
},
"meta": {}
}
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
body | body | RequestAccountIds | mandatory | Array of specific accountIds to obtain scheduled payments for. The accounts specified are the source of funds for the payments returned |
Example responses
200 Response
{
"data": {
"scheduledPayments": [
{
"scheduledPaymentId": "string",
"nickname": "string",
"payerReference": "string",
"payeeReference": "string",
"status": "ACTIVE",
"from": {
"accountId": "string"
},
"paymentSet": [
{
"to": {
"toUType": "accountId",
"accountId": "string",
"payeeId": "string",
"nickname": "string",
"payeeReference": "string",
"digitalWallet": {
"name": "string",
"identifier": "string",
"type": "EMAIL",
"provider": "PAYPAL_AU"
},
"domestic": {
"payeeAccountUType": "account",
"account": {
"accountName": "string",
"bsb": "string",
"accountNumber": "string"
},
"card": {
"cardNumber": "string"
},
"payId": {
"name": "string",
"identifier": "string",
"type": "ABN"
}
},
"biller": {
"billerCode": "string",
"crn": "string",
"billerName": "string"
},
"international": {
"beneficiaryDetails": {
"name": "string",
"country": "string",
"message": "string"
},
"bankDetails": {
"country": "string",
"accountNumber": "string",
"bankAddress": {
"name": "string",
"address": "string"
},
"beneficiaryBankBIC": "string",
"fedWireNumber": "string",
"sortCode": "string",
"chipNumber": "string",
"routingNumber": "string",
"legalEntityIdentifier": "string"
}
}
},
"isAmountCalculated": true,
"amount": "string",
"currency": "string"
}
],
"recurrence": {
"nextPaymentDate": "string",
"recurrenceUType": "eventBased",
"onceOff": {
"paymentDate": "string"
},
"intervalSchedule": {
"finalPaymentDate": "string",
"paymentsRemaining": 1,
"nonBusinessDayTreatment": "AFTER",
"intervals": [
{
"interval": "string",
"dayInInterval": "string"
}
]
},
"lastWeekDay": {
"finalPaymentDate": "string",
"paymentsRemaining": 1,
"interval": "string",
"lastWeekDay": "FRI",
"nonBusinessDayTreatment": "AFTER"
},
"eventBased": {
"description": "string"
}
}
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingScheduledPaymentsListV2 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Payees
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/payees HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/payees',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/payees
Obtain a list of pre-registered payees.
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
type | query | string | optional | Filter on the payee type field. In addition to normal type field values, ALL can be specified to retrieve all payees. If absent the assumed value is ALL |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Enumerated Values
Parameter | Value |
---|---|
type | ALL |
type | BILLER |
type | DIGITAL_WALLET |
type | DOMESTIC |
type | INTERNATIONAL |
Example responses
200 Response
{
"data": {
"payees": [
{
"payeeId": "string",
"nickname": "string",
"description": "string",
"type": "BILLER",
"creationDate": "string"
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingPayeeListV2 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Payee Detail
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/payees/{payeeId} HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
x-fapi-interaction-id: string
x-fapi-auth-date: string
x-fapi-customer-ip-address: string
x-cds-client-headers: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string',
'x-fapi-interaction-id':'string',
'x-fapi-auth-date':'string',
'x-fapi-customer-ip-address':'string',
'x-cds-client-headers':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/payees/{payeeId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/payees/{payeeId}
Obtain detailed information on a single payee.
Note that the payee sub-structure should be selected to represent the payment destination only rather than any known characteristics of the payment recipient.
Obsolete versions: v1
Endpoint Version
Version | 2 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
payeeId | path | ASCIIString | mandatory | The ID used to locate the details of a particular payee |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
x-fapi-interaction-id | header | string | optional | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
x-fapi-auth-date | header | string | conditional | The time when the customer last logged in to the Data Recipient Software Product as described in [FAPI-1.0-Baseline]. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. |
x-fapi-customer-ip-address | header | string | optional | The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. |
x-cds-client-headers | header | Base64 | conditional | The customer's original standard http headers Base64 encoded, including the original User Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. |
Example responses
200 Response
{
"data": {
"payeeId": "string",
"nickname": "string",
"description": "string",
"type": "BILLER",
"creationDate": "string",
"payeeUType": "biller",
"biller": {
"billerCode": "string",
"crn": "string",
"billerName": "string"
},
"domestic": {
"payeeAccountUType": "account",
"account": {
"accountName": "string",
"bsb": "string",
"accountNumber": "string"
},
"card": {
"cardNumber": "string"
},
"payId": {
"name": "string",
"identifier": "string",
"type": "ABN"
}
},
"digitalWallet": {
"name": "string",
"identifier": "string",
"type": "EMAIL",
"provider": "PAYPAL_AU"
},
"international": {
"beneficiaryDetails": {
"name": "string",
"country": "string",
"message": "string"
},
"bankDetails": {
"country": "string",
"accountNumber": "string",
"bankAddress": {
"name": "string",
"address": "string"
},
"beneficiaryBankBIC": "string",
"fedWireNumber": "string",
"sortCode": "string",
"chipNumber": "string",
"routingNumber": "string",
"legalEntityIdentifier": "string"
}
}
},
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingPayeeByIdV2 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. | |
200 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
400 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
404 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
406 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. | |
422 | x-fapi-interaction-id | string | An [RFC4122] UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction. |
Get Products
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/products HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/products',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/products
Obtain a list of products that are currently openly offered to the market
Note that the results returned by this end point are expected to be ordered in descending order according to lastUpdated
.
Conventions
In the product reference payloads there are a number of recurring conventions that are explained here, in one place.
Arrays Of Features
In the product detail payload there are a number of arrays articulating generic features, constraints, prices, etc. The intent of these arrays is as follows:
- Each element in an array has the same structure so that clients can reliably interpret the payloads
- Each element as a type element that is an enumeration of the specific aspect of a product being described, such as types of fees.
- Each element has a field name additionalValue. This is a generic field with contents that will vary based on the type of object being described. The contents of this field for the ADDITIONAL_CARDS feature is the number of cards allowed while the contents of this field for the MAX_LIMIT constraint would be the maximum credit limit allowed for the product.
- An element in these arrays of the same type may appear more than once. For instance, a product may offer two separate loyalty programs that the customer can select from. A fixed term mortgage may have different rates for different term lengths.
- An element in these arrays may contain an additionalInfo and additionalInfoUri field. The additionalInfo field is used to provide displayable text clarifying the purpose of the element in some way when the product is presented to a customer. The additionalInfoUri provides a link to externally hosted information specifically relevant to that feature of the product.
- Depending on the type of data being represented there may be additional specific fields.
URIs To More Information
As the complexities and nuances of a financial product can not easily be fully expressed in a data structure without a high degree of complexity it is necessary to provide additional reference information that a potential customer can access so that they are fully informed of the features and implications of the product. The payloads for product reference therefore contain numerous fields that are provided to allow the product holder to describe the product more fully using a web page hosted on their online channels.
These URIs do not need to all link to different pages. If desired, they can all link to a single hosted page and use difference HTML anchors to focus on a specific topic such as eligibility or fees.
Linkage To Accounts
From the moment that a customer applies for a product and an account is created the account and the product that spawned it will diverge. Rates and features of the product may change and a discount may be negotiated for the account.
For this reason, while productCategory is a common field between accounts and products, there is no specific ID that can be used to link an account to a product within the regime.
Similarly, many of the fields and objects in the product payload will appear in the account detail payload but the structures and semantics are not identical as one refers to a product that can potentially be originated and one refers to an account that actually has been instantiated and created along with the associated decisions inherent in that process.
Dates
It is expected that data consumers needing this data will call relatively frequently to ensure the data they have is representative of the current offering from a bank. To minimise the volume and frequency of these calls the ability to set a lastUpdated field with the date and time of the last update to this product is included. A call for a list of products can then be filtered to only return products that have been updated since the last time that data was obtained using the updated-since query parameter.
In addition, the concept of effective date and time has also been included. This allows for a product to be marked for obsolescence, or introduction, from a certain time without the need for an update to show that a product has been changed. The inclusion of these dates also removes the need to represent deleted products in the payload. Products that are no long offered can be marked not effective for a few weeks before they are then removed from the product set as an option entirely.
Endpoint Version
Version | 3 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
effective | query | string | optional | Allows for the filtering of products based on whether the current time is within the period of time defined as effective by the effectiveFrom and effectiveTo fields. Valid values are ‘CURRENT’, ‘FUTURE’ and ‘ALL’. If absent defaults to 'CURRENT' |
updated-since | query | DateTimeString | optional | Only include products that have been updated after the specified date and time. If absent defaults to include all products |
brand | query | string | optional | Filter results based on a specific brand |
product-category | query | string | optional | Used to filter results on the productCategory field applicable to accounts. Any one of the valid values for this field can be supplied. If absent then all accounts returned. |
page | query | PositiveInteger | optional | Page of results to request (standard pagination) |
page-size | query | PositiveInteger | optional | Page size to request. Default is 25 (standard pagination) |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
Enumerated Values
Parameter | Value |
---|---|
effective | ALL |
effective | CURRENT |
effective | FUTURE |
product-category | BUSINESS_LOANS |
product-category | CRED_AND_CHRG_CARDS |
product-category | LEASES |
product-category | MARGIN_LOANS |
product-category | OVERDRAFTS |
product-category | PERS_LOANS |
product-category | REGULATED_TRUST_ACCOUNTS |
product-category | RESIDENTIAL_MORTGAGES |
product-category | TERM_DEPOSITS |
product-category | TRADE_FINANCE |
product-category | TRANS_AND_SAVINGS_ACCOUNTS |
product-category | TRAVEL_CARDS |
Example responses
200 Response
{
"data": {
"products": [
{
"productId": "string",
"effectiveFrom": "string",
"effectiveTo": "string",
"lastUpdated": "string",
"productCategory": "BUSINESS_LOANS",
"name": "string",
"description": "string",
"brand": "string",
"brandName": "string",
"applicationUri": "string",
"isTailored": true,
"additionalInformation": {
"overviewUri": "string",
"termsUri": "string",
"eligibilityUri": "string",
"feesAndPricingUri": "string",
"bundleUri": "string",
"additionalOverviewUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalTermsUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalEligibilityUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalFeesAndPricingUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalBundleUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
]
},
"cardArt": [
{
"title": "string",
"imageUri": "string"
}
]
}
]
},
"links": {
"self": "string",
"first": "string",
"prev": "string",
"next": "string",
"last": "string"
},
"meta": {
"totalRecords": 0,
"totalPages": 0
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingProductListV2 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
422 | Unprocessable Entity | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. |
Get Product Detail
Code samples
GET https://data.holder.com.au/cds-au/v1/banking/products/{productId} HTTP/1.1
Host: data.holder.com.au
Accept: application/json
x-v: string
x-min-v: string
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-v':'string',
'x-min-v':'string'
};
fetch('https://data.holder.com.au/cds-au/v1/banking/products/{productId}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
GET /banking/products/{productId}
Obtain detailed information on a single product offered openly to the market.
Endpoint Version
Version | 4 |
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
productId | path | ASCIIString | mandatory | ID of the specific product requested |
x-v | header | string | mandatory | Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between x-min-v and x-v. If the value of x-min-v is equal to or higher than the value of x-v then the x-min-v header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See HTTP Headers |
x-min-v | header | string | optional | Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between x-min-v and x-v. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. |
Example responses
200 Response
{
"data": {
"productId": "string",
"effectiveFrom": "string",
"effectiveTo": "string",
"lastUpdated": "string",
"productCategory": "BUSINESS_LOANS",
"name": "string",
"description": "string",
"brand": "string",
"brandName": "string",
"applicationUri": "string",
"isTailored": true,
"additionalInformation": {
"overviewUri": "string",
"termsUri": "string",
"eligibilityUri": "string",
"feesAndPricingUri": "string",
"bundleUri": "string",
"additionalOverviewUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalTermsUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalEligibilityUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalFeesAndPricingUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
],
"additionalBundleUris": [
{
"description": "string",
"additionalInfoUri": "string"
}
]
},
"cardArt": [
{
"title": "string",
"imageUri": "string"
}
],
"bundles": [
{
"name": "string",
"description": "string",
"additionalInfo": "string",
"additionalInfoUri": "string",
"productIds": [
"string"
]
}
],
"features": [
{
"featureType": "ADDITIONAL_CARDS",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"constraints": [
{
"constraintType": "MAX_BALANCE",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"eligibility": [
{
"eligibilityType": "BUSINESS",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"fees": [
{
"name": "string",
"feeType": "DEPOSIT",
"amount": "string",
"balanceRate": "string",
"transactionRate": "string",
"accruedRate": "string",
"accrualFrequency": "string",
"currency": "string",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string",
"discounts": [
{
"description": "string",
"discountType": "BALANCE",
"amount": "string",
"balanceRate": "string",
"transactionRate": "string",
"accruedRate": "string",
"feeRate": "string",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string",
"eligibility": [
{
"discountEligibilityType": "BUSINESS",
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
]
}
]
}
],
"depositRates": [
{
"depositRateType": "BONUS",
"rate": "string",
"calculationFrequency": "string",
"applicationFrequency": "string",
"tiers": [
{
"name": "string",
"unitOfMeasure": "DAY",
"minimumValue": 0,
"maximumValue": 0,
"rateApplicationMethod": "PER_TIER",
"applicabilityConditions": {
"additionalInfo": "string",
"additionalInfoUri": "string"
},
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"lendingRates": [
{
"lendingRateType": "BUNDLE_DISCOUNT_FIXED",
"rate": "string",
"comparisonRate": "string",
"calculationFrequency": "string",
"applicationFrequency": "string",
"interestPaymentDue": "IN_ADVANCE",
"repaymentType": "INTEREST_ONLY",
"loanPurpose": "INVESTMENT",
"tiers": [
{
"name": "string",
"unitOfMeasure": "DAY",
"minimumValue": 0,
"maximumValue": 0,
"rateApplicationMethod": "PER_TIER",
"applicabilityConditions": {
"additionalInfo": "string",
"additionalInfoUri": "string"
},
"additionalInfo": "string",
"additionalInfoUri": "string"
}
],
"additionalValue": "string",
"additionalInfo": "string",
"additionalInfoUri": "string"
}
]
},
"links": {
"self": "string"
},
"meta": {}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResponseBankingProductByIdV4 |
400 | Bad Request | The following error codes MUST be supported: |
ResponseErrorListV2 |
404 | Not Found | The following error codes MUST be supported: |
ResponseErrorListV2 |
406 | Not Acceptable | The following error codes MUST be supported: |
ResponseErrorListV2 |
Response Headers
Status | Header | Type | Format | Description |
---|---|---|---|---|
200 | x-v | string | The version of the API end point that the data holder has responded with. |
Schemas
RequestAccountIds
{
"data": {
"accountIds": [
"string"
]
},
"meta": {}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
data | object | mandatory | none |
» accountIds | [string] | mandatory | none |
meta | Meta | optional | none |
ResponseBankingProductListV2
{
"data": {
"products": [
{
"productId": "string",
"effectiveFrom": "string",
"effectiveTo": "string",
"lastUpdated": "string",
"productCategory": "BUSINESS_LOANS",