Make corrections to Register base URLs and indicate the base URL for all endpoints

[nils-work]

Description

Two Register APIs do not have their correct location defined currently. While correcting these, it may be helpful to extend the way the base URIs are presented for all endpoints, particularly to provide clarity to new users.

The base URI and TLS/MTLS requirements for endpoints are only described in summary tables that are separate to the actual endpoint definitions.

For example -

• Register - the detail is in two tables at the top of the section
• Security Endpoints (for Data Holders and Data Recipients) - is a long section with a table for each endpoint and also a summary table at the end

Area Affected

• The Register APIs section includes tables referring to two Base URLs and TLS/mTLS requirements, but the set of APIs actually require three different base paths split across this matrix.

• The locations for Get JWKS and Get OpenId Provider Config are not correctly defined.

• The location for some Register endpoints include a base path component, while others do not.

Change Proposed

Update the existing Register APIs table to include the respective base in each row, but also consider specifying the relevant Base URI alongside each endpoint definition in the Standards.

Changes to the Register APIs table (name and base value)	Current name	Proposed name	Current base value	Actual base value
Production TLS	RegisterPublicBaseUri	https://api.cdr.gov.au	https://api.cdr.gov.au/cdr-register/v1
(not defined)	RegisterInfoSecBaseUri	(not defined)	https://api.cdr.gov.au/idp
Production MTLS	RegisterResourceBaseUri	https://secure.api.cdr.gov.au	https://secure.api.cdr.gov.au/cdr-register/v1

Sample of Register endpoints affected

• Get OpenId Provider Config The code sample shows only <register-base-url> but the endpoint should refer to <RegisterInfoSecBaseUri>

• Get JWKS The code sample shows only <register-base-url> but the endpoint should refer to <RegisterPublicBaseUri>

• Get Data Holder Brands The code sample shows only <register-base-url> but the endpoint should refer to <RegisterResourceBaseUri>

Sample of other participant endpoints that could benefit from an equivalent change

• Get Accounts The code sample shows only data.holder.com.au but the endpoint should refer to the holder <ResourceBaseUri>

• Get Status The code sample shows only data.holder.com.au but the endpoint should refer to the holder <PublicBaseUri>

• Get Metrics The code sample shows only data.holder.com.au but the endpoint should refer to the holder <AdminBaseUri>

• Get Generic Plans The code sample shows only /energy/plans but the endpoint should refer to the holder <PublicBaseUri> (/energy/plans)

[perlboy]

It pains me to say it but it isn't that easy @nils-work. I'm not particularly bothered about the examples so do whatever however when referencing the Register openapi spec:

• The following endpoint assumes a base uri of /cdr-register/v1: /jwks
• The following endpoint assumes a base uri of /idp: /.well-known/openid-configuration
• The rest assume a base uri of /

Further the default server url in the spec is <register-base-url> which is actually wrong cause of the above assumed base uris. The main challenge actually lies in that base uri for servers because, if it is changed to /cdr-register/v1 (which would align with the Holder specs) all of the api endpoints would now have their paths changed (which will break a large chunk of codegen). Additionally /idp will be abandoned although, maybe that's not a bad thing and it should simply be defined as a token auth security scheme instead 🤷 .

Anyways, alignment seems like a good idea but it seems unlikely to be a "simple" documentation fix, I'm unsure how it could be staged effectively.

[nils-work]

Related issue - https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/516

[ACCC-CDR]

The ACCC requests that this change be confined to documentation updates, specifically:

• correcting the endpoint for Get OpenId Provider config to: /idp/.well-known/openid-configuration
• correcting the endpoint for Get JWKS to: /cdr-register/v1/jwks

We contend that making substantive changes to base URIs is a breaking change, as others have already mentioned. Insofar as this is desirable (a question we express no view on at present), it should be considered separately to the abovementioned corrections, which are strictly documentation changes and will not impact existing implementations in any way.