Home / Specifications / cdsc-wg1-02
- Client Registration
Client Registration
Looking for a more human-readable summary of this specification? Check out our overview.
Below is a rendering of the original specification source: https://github.com/daniel-utilityapi/Connectivity/blob/main/specifications/cdsc-wg1-02.md
CDSC-WG1-02 - Client Registration
Abstract đź”—
This specification defines how utilities and other central entities (“Servers”) may allow third parties (“Clients”) to register, configure, and maintain connectivity with the utility or other central entity. This specification mostly extends various OAuth specifications (Dynamic Client Registration, Authorization Server Metadata, and more) to create a robust framework for offering secure, streamlined, and standardized connectivity between utilities and third parties.
Status đź”—
WARNING: This specification is a DRAFT and has not achieved consensus by the working group.
Copyright đź”—
TODO
Table of Contents đź”—
- 1. Introduction
- 2. Terminology
- 3. Authorization Server Metadata
- 3.1. Metadata URL
- 3.2. Metadata Object Format
- 3.3. Scopes Supported
- 3.4. Scope Descriptions Object Format
- 3.5. Registration Field Object Format
- 3.6. Registration Field Types
- 3.7. Registration Field Formats
- 3.8. Authorization Details Field Object Format
- 3.9. Authorization Details Field Formats
- 3.10. Authorization Details Field Choice Object Format
- 4. Client Registration Process
- 5. Clients API
- 6. Messages API
- 7. Credentials API
- 8. Grants API
- 9. Server-Provided Files API
- 10. Extensions
- 11. Examples
- 12. Security Considerations
- 13. References
- 14. Acknowledgments
- 15. Authors’ Addresses
1. Introduction đź”—
This specification was developed as part of the global effort to combat the climate crisis. Specifically, in order to scalably measure carbon emissions of organizations and calculate the impact of deploying and operating clean energy technologies, companies need an efficient means to register and interact with energy utilities and other similar entities.
There are thousands of utilities serving customers across the world, and each have their own way of providing access to privileged functionality and data. This specification defines a way for these utilities and other entities (“Servers”) to provide a standardized, structured process for external users and companies (“Clients”) to register and obtain secure access to privileged functionality and data. By offering a standardized Client registration and management protocol, utilities and other entities can enable secure interoperability with other external systems providing climate-change fighting services such as carbon tracking, decarbonization measures, grid flexibility capabilities, and energy benchmarking.
This specification does NOT describe what specific privileged functionality or data is offered to Clients as part of their registration. Instead, relevant stakeholders are encouraged to write Extensions to this specification that enable various use cases that need access to privileged functionality or data. For example, this specification may be extended to define a method for Clients to be able to access customer-authorized energy usage data.
2. Terminology đź”—
🔗 “Server” - The entity hosting the specified endpoints. A Server can be an energy utility or another type of entity that want to provide access to privileged functionality or data. These entities can include, but are not limited to, distribution utilities, grid operators, electric retailers, community choice aggregators, government agencies, data warehouses, and private infrastructure providers.
🔗 “Client” - The entity requesting Server’s metadata endpoints. A Client can be any organization or user seeking to register with a Server for a specific scope of access. These entities can include, but are not limited to, carbon tracking applications, electric vehicle companies, clean energy technology providers, commercial utility customers, grid management applications, and energy efficiency organizations.
🔗 Referenced Technologies: “HTTPS”, “Request Methods”, “Status Codes”, “JSON”, “OAuth”, TODO: add more as needed are defined by their referenced standards documents.
🔗 “string” - A series of unicode characters as defined in RFC 8259.
🔗 “integer” - A positive integer value as defined by int
in RFC 8259.
🔗 “decimal” - A decimal value as defined by number
in RFC 8259.
🔗 “null” - The null
value defined in RFC 8259.
🔗 “boolean” - Either true
or false
defined in RFC 8259.
🔗 “Array” - A list of objects or values as defined by Arrays
in RFC 8259.
🔗 “Map” - A JSON object as defined by Objects
in RFC 8259.
🔗 “date” - A string representing date in the format of full-date
as defined by RFC 3339 (e.g. “2024-01-01”).
🔗 “datetime” - A string representing date and time in the format of date-time
as defined by RFC 3339 (e.g. “2024-01-01T00:00:00Z”).
🔗 “URL” - A string representing resource as defined in RFC 3986 (e.g. “https://example.com/page1”).
🔗 “JWK Public Encryption Key” - A JSON object representing a public key as defined in RFC 7517 where the use field MUST contain the value enc
.
🔗 Key Words: “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” are defined in accordance with BCP 14.
3. Authorization Server Metadata đź”—
To enable automated Client registration, Servers MUST host an endpoint with structured metadata about how to submit a registration request, as well as functionality and data capabilities offered by the Server. The requirements for hosting this metadata endpoint follows OAuth 2.0 Authorization Server Metadata with several additions for Carbon Data Specification (CDS) functionality described in the following sections.
3.1. Metadata URL đź”—
Following OAuth’s Obtaining Authorization Server Metadata process, a Server’s Authorization Server Metadata Object is retrieved by making an HTTPS request to a specified URL.
To ensure discoverability to the specified URL, this specification extends CDSC-WG1-01 Server Capabilities to require the following values:
oauth
- string - (REQUIRED) Including Client Registration via OAuth in the list of a Server’s available capabilities
As well as extending the CDSC-WG1-01 Metadata Object Format to require the following values:
oauth_metadata
- URL - (REQUIRED) Where Clients can obtain the Server’s Authorization Server Metadata Object
In addition to requiring that the URL be included in the CDSC-WG1-01 Metadata Object Format, Servers MAY also configure the URL such that it conforms to the default Well-Known URI format, which can increase interoperability beyond the above specified CDSC-WG1-01 extension.
3.2. Metadata Object Format đź”—
A Server’s Authorization Server Metadata Object follows OAuth’s Authorization Server Metadata object format with the following modifications from OPTIONAL or RECOMMENDED to REQUIRED:
registration_endpoint
- URL - (REQUIRED) OAuth’s Dynamic Client Registration functionality is required to enable the Client Registration Process.scopes_supported
- Array[string] - (REQUIRED) The scopes in this array MUST represent a union of all scopeid
values contained in thecds_scope_descriptions
objects.service_documentation
- URL - (REQUIRED) Developer documentation is required by the Server to help streamline Client integration.op_policy_uri
- URL - (REQUIRED) Policies for Clients registering is required.op_tos_uri
- URL - (REQUIRED) Terms of use for Clients registering is required.revocation_endpoint
- URL - (REQUIRED) OAuth’s Token Revocation functionality is required.introspection_endpoint
- URL - (REQUIRED) OAuth’s Token Introspection functionality is required.code_challenge_methods_supported
- Array[string] - (REQUIRED) The code challenge methods in this array MUST represent a union of allcode_challenge_methods_supported
values contained in thecds_scope_descriptions
objects.
In addition to the standard set of OAuth Authorization Server Metadata values, this specification also requires the following OAuth extension capabilities to be included in the metadata object values:
authorization_details_types_supported
- Array[string] - (REQUIRED) OAuth’s Rich Authorization Requests functionality is required. This array of values MUST be the same asscopes_supported
.pushed_authorization_request_endpoint
- URL - (REQUIRED) OAuth’s Pushed Authorization Requests functionality is required.
In addition to the above additionally required set of OAuth Authorization Server Metadata values, this specification clarifies use of the following OAuth standard values:
response_types_supported
- Array[string] - (REQUIRED) The response types in this array MUST represent a union of allresponse_types_supported
values contained in thecds_scope_descriptions
objects.grant_types_supported
- Array[string] - (REQUIRED) The response types in this array MUST represent a union of allgrant_types_supported
values contained in thecds_scope_descriptions
objects.token_endpoint_auth_methods_supported
- Array[string] - (REQUIRED) The response types in this array MUST represent a union of alltoken_endpoint_auth_methods_supported
values contained in thecds_scope_descriptions
object.
In addition to OAuth capabilities included in the metadata object, this specification adds the following Carbon Data Specification (CDS) values:
cds_oauth_version
- string - (REQUIRED) The version of the CDS-WG1-02 Client Registration specification that the Server has implemented, which for this version of the specification isv1
cds_human_registration
- URL - (REQUIRED) Where Clients who do not have the technical capacity to use theregistration_endpoint
can visit to manually register a Client using a user devicecds_test_accounts
- URL - (REQUIRED) Where Clients can find developer documentation on what test account credentials may be used for testing OAuthresponse_type=code
authorization requestscds_clients_api
- URL - (REQUIRED) The base url for the Clients APIcds_messages_api
- URL - (REQUIRED) The base url for the Messages APIcds_credentials_api
- URL - (REQUIRED) The base url for the Credentials APIcds_grants_api
- URL - (REQUIRED) The base url for the Grants APIcds_scope_descriptions
- Map[ScopeDescription] - (REQUIRED) An object providing additional information about what Scope values listed inscopes_supported
mean. This object MUST include a key for each Scope listed inscopes_supported
with a Scope Description as that key’s value.cds_registration_fields
- Map[RegistrationField] - (REQUIRED) An object providing additional information about Registration Field that are referenced in Scope Description’sregistration_requirements
list. This object MUST include a key for each Registration Fieldid
included in theregistration_requirements
lists in the metadata object with a Registration Field as that key’s value. If allregistration_requirements
lists are empty, this reference object is an empty object ({}
).
Scope functionality described by Scope Description objects included in the cds_scope_descriptions
object MUST be available for all of the scope’s coverage, as described by the Scope Description’s coverages_supported
list, up to any limits specified in the scopes authorization details, as described by the Scope Description’s authorization_details_fields_supported
Authorization Details object’s limit
values.
For situations where the same scope is available for multiple groups of coverages and limits, multiple Scope Description entries with different id
values MUST be included.
For example, if a Server offers a scope that grants access to historical customer usage data, offering 24 months of usage history for electricity service contracts and and 12 months of history for natural gas service contracts, the Server MUST include two Scope Descriptions with different id
values that include only the coverage and limits of that scope’s functionality.
Other values not mentioned here but listed in specifications for the Authorization Server Metadata specification or other extensions MAY be included as described in their respective specifications.
3.3. Scopes Supported đź”—
This section defines scopes that MAY be included in a Server’s scopes_supported
list.
Servers MUST include at least the client_admin
and grant_admin
scopes in the Server’s scopes_supported
list.
Extensions MAY define and Servers MAY include additional scopes to the above list of defined scopes, so long as they include Scope Descriptions for the scopes in the cds_scope_descriptions
.
Extensions are RECOMMENDED to define additional scopes with their specification name or abbreviation as a prefix to prevent namespace collisions with other scopes defined by other extensions and Servers, such as examplespec_*
.
Server are RECOMMENDED to include their name or other relevant identifier as a prefix when adding additional scopes custom to their server, such as examplepowercompany_*
.
Clients MUST ignore any scopes in a Server’s scopes_supported
list for which the Client is not compatible.
3.3.1 Client Admin Scope đź”—
This is the main administrative scope that grants access for the Client to manage their registration using the defined APIs in this specification.
The following are how the Scope Descriptions fields MUST be configured for this scope:
id
is"client_admin"
.name
is"Client Admin"
.description
is"This scope grants administrative access to the Client management APIs."
.documentation
is a URL for the Server’s documentation on theclient_admin
scope. Servers MAY set the URL to an online publicly-available copy of this specification as adequate documentation for this scope.registration_requirements
is[]
.registration_optional
is[]
.response_types_supported
is[]
.grant_types_supported
is["client_credentials"]
.token_endpoint_auth_methods_supported
is["client_secret_basic"]
.code_challenge_methods_supported
is[]
.coverages_supported
is[]
.authorization_details_fields_supported
is[]
.
3.3.2 Grant Admin Scope đź”—
A scope for administratively gaining access to a specific Grant data and functionality. Since Servers MAY arbitrarily create Grant objects included in the Grants API, this scope serves as an additional method of gaining access to previously created Grant scopes by Client administrators.
The following are how the Scope Descriptions fields MUST be configured for this scope:
id
is"grant_admin"
.name
is"Grant Admin"
.description
is"This scope grants administrative access to previously created Grants."
.documentation
is a URL for the Server’s documentation on thegrant_admin
scope. Servers MAY set the URL to an online publicly-available copy of this specification as adequate documentation for this scope.registration_requirements
is[]
.registration_optional
is[]
.response_types_supported
is[]
.grant_types_supported
is["client_credentials"]
.token_endpoint_auth_methods_supported
is["client_secret_basic"]
.code_challenge_methods_supported
is[]
.coverages_supported
is[]
.authorization_details_fields_supported
is a JSON array with the following two entries of Authorization Details Field Objects.- Client ID:
id
isclient_id
.name
is"Client object identifier"
.description
is"The Client object identifier for which the Grant is issued."
.documentation
is a URL for the Server’s documentation on theclient_id
authorization details field. Servers MAY set the URL to an online publicly-available copy of this specification as adequate documentation for this authorization details field.format
isstring
.is_required
istrue
.default
is not included.relative_date_limit
is not included.absolute_date_limit
is not included.limit
is not included.choices
is not included.
- Grant ID:
id
isgrant_id
.name
is"Grant identifier"
.description
is"The Grant identifier for which the returned access_token will be given access."
.documentation
is a URL for the Server’s documentation on thegrant_id
authorization details field. Servers MAY set the URL to an online publicly-available copy of this specification as adequate documentation for this authorization details field.format
isstring
.is_required
istrue
.default
is not included.relative_date_limit
is not included.absolute_date_limit
is not included.limit
is not included.choices
is not included.
- Client ID:
Server MUST only approve submissions of this scope to the token endpoint with a single authorization details entry to the token endpoint, ensuring the access token returned is only valid for one grant_id
.
Servers MUST only approve submissions of this scope to the token endpoint when the grant_id
is for a Grant that has a matching client_id
, has a non-empty enabled_scope
value (i.e. the Grant is not disabled) and neither client_admin
or grant_admin
are part of the scope
.
3.3.3 Server-Provided Files Scope đź”—
A scope for Servers to grant Client access to arbitrary files that the Server wishes to securely share with the Client.
Grants with this scope MUST be created by the Server and appear on the Grants API and include authorization_details
entries that list the file_id
values that are being shared for that Grant.
The following are how the Scope Descriptions fields MUST be configured for this scope:
id
is"server_provided_files"
.name
is"Server-Provided Files"
.description
is"This scope grants access to specific files that the Server wants make available to the Client."
.documentation
is a URL for the Server’s documentation on theserver_provided_files
scope. Servers MAY set the URL to an online publicly-available copy of this specification as adequate documentation for this scope.registration_requirements
is[]
.registration_optional
is[]
.response_types_supported
is[]
.grant_types_supported
is[]
.token_endpoint_auth_methods_supported
is[]
.code_challenge_methods_supported
is[]
.coverages_supported
is[]
.authorization_details_fields_supported
is a JSON array with a single entry Authorization Details Field Object with the following fields.id
isfile_id
.name
is"File identifier"
.description
is"A file provided by the Server that may be accessed by the Client as part of the Grant."
.documentation
is a URL for the Server’s documentation on thefile_id
authorization details field. Servers MAY set the URL to an online publicly-available copy of this specification as adequate documentation for this authorization details field.format
isstring
.is_required
istrue
.default
is not included.relative_date_limit
is not included.absolute_date_limit
is not included.limit
is not included.choices
is not included.
Since Grants with the scope are only created by Servers, Client do not receive an authorization code or access token for that Grant with which they may access the files. Instead, to access the files, Clients MUST submit a client_credentials
grant with the scope of grant_admin
and an authorization_details
containing the client_id
and grant_id
for the Grant the Client found via the Grants API.
3.4. Scope Descriptions Object Format đź”—
Scope Description objects are formatted as JSON objects and contain named values. The following values are included in the default list available in scope description objects.
id
- string - (REQUIRED) The unique identifier of the scope. This MUST be the same value as the object key the Metadata Object’scds_scope_descriptions
object.name
- string - (REQUIRED) A human-readable name of the scope.description
- string - (REQUIRED) A human-readable description of what access or actions the scope will enable.documentation
- URL - (REQUIRED) Where developers can find documentation for the scope.registration_requirements
- Array[string] - (REQUIRED) A list of any registration fields that MUST be submitted with Client Registration Requests or requirements that must be completed after registration before the scope is available to use in the Server’s production environment. All values in this array MUST be included in the Metadata Object’scds_registration_fields
object for a complete description of the requirement. If no additional requirements are needed, this value is an empty array ([]
).registration_optional
- Array[string] - (REQUIRED) A list of any registration fields that Clients MAY submit with the Client Registration Requests. If no additional fields are available, this value is an empty array ([]
).response_types_supported
- Array[string] - (REQUIRED) The OAuthresponse_type
values that can be used with this scope. This value follows the same behavior as OAuth’s Metadata objectresponse_types_supported
, except that this value represents the response types supported for this individual scope and not all scopes for the Client. If a scope is not available for OAuth authorization requests (e.g. aclient_credentials
-only scope), this value is an empty array ([]
).grant_types_supported
- Array[string] - (REQUIRED) The OAuth grant type values that can be used with this scope. This value follows the same behavior as OAuth’s Metadata objectgrant_types_supported
, except that this value represents the grant types supported for this individual scope and not all scopes for the Client. This array MUST contain at least one grant type.token_endpoint_auth_methods_supported
- Array[string] - (REQUIRED) The OAuth client authentication methods that can be used for granting tokens with this scope. This value follows the same behavior as OAuth’s Metadata objecttoken_endpoint_auth_methods_supported
, except that this value represents the client authentication methods supported for this individual scope and not all scopes for the Client. A value of"none"
this array indicates that the scope may be used for public application without using a client secret.code_challenge_methods_supported
- Array[string] - (REQUIRED) For scope descriptions wheregrant_types_supported
includes the valueauthorization_code
, OAuth’s Proof Key for Code Exchange by OAuth Public Clients functionality is required, and Servers MUST offerS256
and MUST NOT offerplain
code verifier methods. For scope descriptions wheregrant_types_supported
does not includeauthorization_code
, no authorization request is performed, so no code challenge is required and this field value is an empty list ([]
).coverages_supported
- Array[string] - (REQUIRED) A list of CDSC-WG1-01 Coverage Entry Objectid
values for which the scope is available by the Server. If the scope provides functionality unrelated to a Server’s coverage entries (e.g. theclient_admin
scope), this value is an empty list ([]
).authorization_details_fields_supported
- Array[AuthorizationDetailsField] - (REQUIRED) A list of fields that MAY be included in Rich Authorization Requests the authorization details object for this scopetype
. If no extra authorization details fields are available, this value is an empty list ([]
).
3.5. Registration Field Object Format đź”—
Registration Field objects are formatted as JSON objects and contain named values. The following values are included in the default list available in registration fields objects.
id
- string - (REQUIRED) The unique identifier of the registration field. This MUST be the same value as the object key the Metadata Object’scds_registration_fields
object.type
- RegistrationFieldType - (REQUIRED) What type of Registration Field this entry is.description
- string - (REQUIRED) A human-readable description of what should be submitted or expected for this registration field.documentation
- URL - (REQUIRED) Where developers can find more information about this registration field.field_name
- string - (OPTIONAL) If type isregistration_field
, this is the name of the field to submit in the Client Registration Request and MUST start withcds_
.format
- RegistrationFieldFormats - (OPTIONAL) If type isregistration_field
, this is the data format that MUST be used in the value of the field.default
- various - (OPTIONAL) If type isregistration_field
and the field is optional, this is the default value that will be used in lieu of the Client submitting a value themselves. Including thisdefault
value in the object indicates the registration field is optional.max_length
- integer - (OPTIONAL) If format is one ofstring
,string_or_null
,url
,url_or_null
,email
, oremail_or_null
, this is the maximum length of the submitted value, if notnull
.max_size
- integer - (OPTIONAL) If format is one ofimage
,image_or_null
,pdf
, orpdf_or_null
, this is the maximum file size of the submitted value before encoding into Base64, if notnull
.amount
- decimal - (OPTIONAL) If type ispayment_required
, this is the amount incurrency
that will be required to complete registration.currency
- string - (OPTIONAL) If type ispayment_required
, this is the monetary currency in ISO 4217 currency code.
3.6. Registration Field Types đź”—
Registration Field types define which type of action the Client or Server will take for that registration field.
Registration Fields can be either something that MUST or MAY be submitted as part of the Client Registration Request, depending on the submitted scope’s registration_requirements
and registration_optional
values, or can be something that a Client must do after registration in order to be full approved for use in the production environment.
The following list of strings are an enumerated set of registration field types that are valid type
values in the registration field object.
registration_field
- This field should be submitted with the Client Registration Request as thefield_name
. This type of registration field MUST also havefield_name
andformat
values. If this field is optional as part of registration,default
must also be defined in the registration field object.internal_review
- This field indicates that the Server will review the registration internally before approving it for production use. Notifications and communication about the status of this internal review will be conveyed using the Messages API.payment_required
- This field indicates that a setup payment will be required before the Server will approve the Client for production use. Notifications and communication about how to pay and confirmation of payment will be conveyed using the Messages API.email_verification
- This field indicates that the Client must verify their email before the Server will approve the Client for production use. Notifications and communication about how to verify the Client’s contact email will be conveyed using the Messages API.
3.7. Registration Field Formats đź”—
Registration Field formats define the data type of submitted values for these fields in Client Registration Requests.
The following list of strings are an enumerated set of registration field formats that are valid format
values in the registration field object.
string
- If required, a string value MUST be submitted.string_or_null
- Same asstring
, only withnull
being an additional possible value.url
- If required, a URL value MUST be submitted.url_or_null
- Same asurl
, only withnull
being an additional possible value.email
- If required, a valid email address string MUST be submitted.email_or_null
- Same asemail
, only withnull
being an additional possible value.boolean
- If required, a boolean value MUST be submitted.boolean_or_null
- Same asboolean
, only withnull
being an additional possible value.image
- If required, a valid image file formatted asimage/jpeg
orimage/png
encoded as a string using Base64 MUST be submitted.image_or_null
- Same asimage
, only withnull
being an additional possible value.pdf
- If required, a valid pdf file formatted encoded using Base64 as a string MUST be submitted.pdf_or_null
- Same aspdf
, only withnull
being an additional possible value.
3.8. Authorization Details Field Object Format đź”—
Authorization Details Field objects are formatted as JSON objects and contain named values. The following values are included in the default list available in authorization details field objects.
id
- string - (REQUIRED) The unique identifier of the authorization details field. This value is used as the key for the field when added toauthorization_details
data fields as part of OAuth’s Rich Authorization Requests.name
- string - (REQUIRED) A human-readable name of the authorization details field.description
- string - (REQUIRED) A human-readable description of what submitting values for this authorization details field means.documentation
- URL - (REQUIRED) Where developers can find more information about this authorization details field.format
- AuthorizationDetailsFieldFormats - (REQUIRED) The data format that MUST be used in the value of the field when including it as a data field inauthorization_details
objects.is_required
- boolean - (REQUIRED) Whether the authorization details field is required or not. If required,authorization_details
MUST be submitted in authorization or token requests with this field included.default
- various - (OPTIONAL) Ifis_required
isfalse
, this is the default value that will be used in lieu of the Client submitting a value themselves. This is also the value that will be used if a basic OAuthscope
string parameter is used instead of anauthorization_details
parameter. Ifis_required
istrue
, this is not included.relative_date_limit
- integer - (OPTIONAL) Ifformat
isrelative_or_absolute_date
and the value is limited by the Server, this is REQUIRED and MUST be the largest relative date range that may be submitted. Servers MUST validate both submitted absolute dates and relative dates against the relative date limit, where when comparing to a submitted absolute date, the current Server date in the Server’s local timezone is used as the relative point of reference. Ifformat
is notrelative_or_absolute_date
, this is not included.absolute_date_limit
- integer - (OPTIONAL) Ifformat
isrelative_or_absolute_date
the value is limited by the Server, this is REQUIRED and MUST be the furthest away date that may be submitted. Servers MUST validate both submitted absolute dates and relative dates against the absolute date limit, where when comparing to a submitted relative date, the current Server date in the Server’s local timezone is used as the relative point of reference.limit
- integer - (OPTIONAL) Ifformat
is one ofint
ordecimal
and the value is limited by the Server, this is REQUIRED and MUST be the largest value that can be the submitted. Ifformat
isstring
and the length of the value is limited by the Server, this is REQUIRED and MUST be the maximum string length that can be the submitted.choices
- Array[AuthorizationDetailsFieldChoice] - (OPTIONAL) Ifformat
ischoice
, this is REQUIRED and MUST be a list of one or more available choice objects.
3.9. Authorization Details Field Formats đź”—
Authorization Details Field formats define the data type of submitted values for these fields in authorization_details
for OAuth’s Rich Authorization Requests.
The following list of strings are an enumerated set of authorization details field formats that are valid format
values in the Authorization Details Field objects.
int
- An integer value.decimal
- A decimal value, which can have any number of significant units, but MUST NOT be stored or handled as a float value, in order to retain the precision of the value throughout Server and Client processing.string
- A string value.string_or_null
- A string value ornull
.boolean
- A boolean value.relative_or_absolute_date
- A relative or absolute date string. Relative dates are formatted as defined byduration
in RFC 3339 Appendix A. For example,P3Y
represents a relative date range of 3 years. Absolute dates are formatted as date (YYYY-MM-DD
). For example,2024-01-02
represents the 2nd of January, 2024. Dates are defined as the date from the perspective of the Server’s local timezone.choice
- A string value from theid
parameter in one of the listed availablechoices
Authorization Details Field Choice objects.jwk_or_null
- A JWK Public Encryption Key object ornull
.
3.10. Authorization Details Field Choice Object Format đź”—
Authorization Details Field Choice objects are formatted as JSON objects and contain named values. The following values are included in the default list available in Authorization Details Field Choice objects.
id
- string - (REQUIRED) The unique identifier of the authorization details field choice. This is used as the value for the relvant field when that field is included in an object as part of aauthorization_details
list.name
- string - (REQUIRED) A human-readable name of the authorization details field choice.description
- string - (REQUIRED) A human-readable description of what submitting this value for the authorizations details field means.documentation
- URL - (REQUIRED) Where developers can find more information about this authorization details field choice.
4. Client Registration Process đź”—
OAuth’s Dynamic Client Registration is used as the basis for initially registering Clients with Servers.
To perform the dynamic registration process, the Client submits a request to the Server’s registration_endpoint
provided in the Server’s Metadata object as described in Client Registration Request.
The Server then responds with either an error or a generated Client registration response as described in Client Registration Response.
4.1. Client Registration Request đź”—
This specification requires Clients and Servers follow the process described in OAuth’s Client Registration Request, with the following modifications.
- Clients MAY submit additional named values that are defined as part of scope
registration_requirements
andregistration_optional
arrays incds_scope_descriptions
objects, using the registration field reference’sfield_name
value as the submitted key in the registration request. - Servers MUST ignore any submitted
redirect_uris
values. Clients MAY later update individual Client objectredirect_uri
values via the Modifying Clients process, when that Client objectresponse_types
list is non-empty.
4.2. Client Registration Response đź”—
This specification requires Servers follow the process described in OAuth’s Client Registration Response, with the following modifications to OAuth’s Client Information Response object.
- The reponse object format MUST be the extended Client object format defined by the Clients API.
- The
scope
value MUST beclient_admin
, indicating that the Client in the response is only used forclient_admin
access. - The
redirect_uris
value MUST be an empty list ([]
). - The
response_types
value MUST be an empty list ([]
). - The
grant_types
value MUST contain only theclient_credentials
grant, indicating that the Client details in the response may only be used forclient_admin
client credentials grant. - The
token_endpoint_auth_method
MUST be set toclient_secret_basic
. - The
client_secret
MUST be included, despite it not being included in the Client object format returned by the Clients API, and set to the same value as theclient_secret
in the created Credential object for the Client object in the response.
Upon valid registration, servers MUST create a Client object with the scope defined as "client_admin"
, even if the client_admin
scope was not included in the Client Registration Request.
This Client object scoped to client_admin
is the one returned as the main Client object as the Client Registration Response.
Servers MUST also create a Client object with the scope defined as "grant_admin"
, though it is not returned as part of the Client Registration response and is only available via the Clients API.
Servers MUST also create Client objects that are configured for any other scopes for which the Client submitted registration and the submission was accepted by the Server.
Servers MAY combine scopes into individual Client objects if the response_types
, grant_types
, and token_endpoint_auth_method
for the scopes are the same.
For each Client object created that has its token_endpoint_auth_method
value as something other than none
, at least one Credential object MUST be created and made available on the Credentials API for the Client to use.
For created Client objects that have a non-empty response_types
list, Servers MUST create a default redirect_uri
value and and set it as the single value in the created Client object redirect_uris
list.
The created redirect_uri
MUST provide functionality such that if specified as part of authorization request parameters, will redirect the user to a receipt of the authorization when the authorization is submitted successfully, or show an error to the user if the authorization is declined or otherwise errors.
This default redirect_uri
allows Clients to request user authorization without needing to operate their own redirect endpoint.
Clients MAY choose to update the redirect_uris
to remove this default or add additional redirect URIs using the Modifying Clients functionality.
Servers MUST NOT create Clients that have both production
and sandbox
values in the same cds_status_options
, so that Client objects cannot be used for both testing and production environments.
For situations where Servers do not initially create a Client with production
as a cds_status_option
, such as when the Server has a manual review step, Servers MUST create a Client object with sandbox
as a cds_status_option
so that Clients MAY being to test their applications immediately after registration.
Then, later if and when the Server decides to allow the Client access to the production environment, the Server MUST create a new Client object with production
as a cds_status_option
.
While Servers MAY support OAuth’s Dynamic Client Registration Management Protocol by including the registration_client_uri
and registration_access_token
values in their registration response, this specification requires that Servers MUST support the Clients API by including the cds_clients_api
value in the registration response as a way for Clients to manage their registrations. The Clients API is needed beyond the OAuth Dynamic Client Registration Management Protocol because as part of registration, Servers create multiple Clients that group the various registered scopes, and OAuth’s Dynamic Client Registration Management Protocol does not support APIs for listing multiple clients or credentials that are created from a single registration request.
5. Clients API đź”—
This specification requires Servers provide a set of Application Programming Interfaces (APIs) allowing Clients to view and edit their Client registrations.
These APIs are authenticated using a Bearer access_token
obtained by the Client using OAuth’s client_credentials
grant process, where the client_id
used is for a Client that includes the client_admin
scope.
5.1. Client Object Format đź”—
Client objects are formatted as JSON objects and contain named values. Client objects are required to follow the same object format as the OAuth Dynamic Client Registration Management Protocol’s Client Metadata, with the following modifications.
The following fields defined in OAuth’s Client Metadata are REQUIRED to be included with all Client objects:
client_id
client_id_issued_at
scope
- If no scope is configured, this value is an empty string (""
).redirect_uris
- If no redirect URIs are configured, this value is an empty list ([]
).token_endpoint_auth_method
- If no auth methods are configured, this value isnull
.grant_types
- If no grant types are configured, this value is an empty list ([]
).response_types
- If no response types are configured, this value is an empty list ([]
).client_name
- If no value is submitted by the Client, the default value is theclient_id
.contacts
- If no contacts are configured, this value is an empty list ([]
).
The following fields defined in OAuth’s Rich Authorization Requests are REQUIRED to be included with all Client objects:
authorization_details_types
The following fields MUST NOT be included, except when the Client object is returned as a Client Registration Response:
client_secret
The following fields MUST NOT be included, since it is moved to the Credentials API:
client_secret_expires_at
Other fields defined in the OAuth’s Client Metadata and its extensions, such as OAuth’s Dynamic Client Registration Management Protocol, remain unmodified in their requirement and behavior.
In addition to the fields defined by OAuth’s Client Metadata and its extensions, the following fields are additionally defined:
cds_created
- datetime - (REQUIRED) When the Client object was created.cds_modified
- datetime - (REQUIRED) When the Client object was last modified.cds_client_uri
- URL - (REQUIRED) Where to submit modifications using the Clients API Modifying Clients functionality. Servers MUST make this URL unique for each Client object.cds_status
- ClientStatus - (REQUIRED) The current status of availability for this Client.cds_status_options
- Array[ClientStatus] - (REQUIRED) Whatcds_status
values to which the Client MAY change the Client when modifying it. For Client objects that have theclient_admin
scope, this list MUST NOT contain thedisabled
value, and for all other Client objects this list MUST contain at least thedisabled
value, so that Clients MAY opt to disable Client objects as needed.cds_server_metadata
- URL - (REQUIRED) Where the Client can find their registration-specific version of the CDSC-WG1-01 Server Metadata. If the Client’s registered scopes have different Scope Descriptions than what is in the publicly availableoauth_metadata
resource, such as more limitedcoverages_supported
or different limits inauthorization_details_fields_supported
, then thecds_server_metadata
MUST be to a resource that has an updatedoauth_metadata
resource with the Client-specific values. If the Client’s CDSC server metadata is no different from the public CDSC server metadata, Servers MAY simply link to the public URL. If this metadata endpoint requires authentication, Servers MUST authenticate Client requests to this endpoint via Bearer access token obtained using OAuth’sclient_credentials
grant with a scope ofclient_admin
, and reject unauthenticated requests with a401 Unauthorized
response code. Clients know that they must use a Bearer token when Servers return a401
response code for this endpoint when the Client makes an unauthenticated request to the endpoint.cds_clients_api
- URL - (REQUIRED) The base url for the Clients API.cds_messages_api
- URL - (REQUIRED) The base url for the Messages API.cds_credentials_api
- URL - (REQUIRED) The base url for the Credentials API.cds_grants_api
- URL - (REQUIRED) The base url for the Grants API.cds_server_provided_files_api
- URL - (OPTIONAL) The base url for the Server-Provided Files API. This MUST be included if the Client’s registration responsescope
string included theserver_provided_files
scope.cds_default_scope
- string - (OPTIONAL) The default scope string used when noscope
parameter is provided as part of an authorization request. This MUST be included ifresponse_types
is not an empty list (i.e. authorization requests are enabled). For the initial registration response, Servers MAY choose to configure the default scope string the same as thescope
field or another subset of default scopes.cds_default_redirect_uri
- URL - (OPTIONAL) The default redirect_uri string used when noredirect_uri
parameter is provided as part of an authorization request. This MUST be included ifresponse_types
is not an empty list (i.e. authorization requests are enabled). For the initial registration response, Servers MUST set this value to the value in theredirect_uris
that was required to be created by the Server that will redirect the user by default to an authorization receipt.cds_default_authorization_details
- Array[OAuth AuthorizationDetail] - (OPTIONAL) The default authorization details list used when noauthorization_details
parameter is provided as part of an authorization request. This MUST be included ifresponse_types
is not an empty list (i.e. authorization requests are enabled). For the initial registration response, Servers MUST set this to an empty list ([]
).
5.2. Client Statuses đź”—
Client object cds_status
values MUST be one of the following:
production
- The Client object MAY be used on the Server’s production systems. For scopes that require user authorization (e.g.response_type
values ofcode
), thiscds_status
indicates that the Client may request authorization from real users.sandbox
- The Client object MAY be used to request access on the Server’s test environment systems. For scopes that require user authorization (i.e.response_type
values ofcode
), thiscds_status
indicates that the Client may request authorization from fictional test users, as provided in the Server’scds_test_accounts
documentation.disabled
- The Client is is disabled.
5.3. Listing Clients đź”—
Clients may request to list Client objects that they have access to by making an HTTPS GET
request, authenticated with a valid Bearer access_token
scoped to the client_admin
scope, to the cds_clients_api
URL included in the Client Registration Response.
The Client listing request responses are formatted as JSON objects and contain the following named values.
clients
- Array[Client] - (REQUIRED) A list of Clients to which the requestingaccess_token
is scoped to have access. If no Clients are accessible, this value is an empty list ([]
). If more than 100 Clients are available to be listed, Servers MAY truncate the list and use thenext
value to link to the next segment of the list of Clients.next
- URL ornull
- Where to request the next segment of the list of Clients. If no next segment exists (i.e. the requester is at the end of the list), this value isnull
.previous
- URL ornull
- Where to request the previous segment of the list of Clients. If no previous segment exists (i.e. the requester is at the front of the list), this value isnull
.
Listings of Client objects MUST be ordered in reverse chronological order by cds_modified
timestamp, where the most recently updated relevant Client MUST be first in each listing.
For Client objects in the listing that are added, removed, or modified by the Server or Client after initial registration, Servers MUST add a message to the listed Messages notifiying the Client that a Client object has been added, removed, or modified. This creates a changelog in the Messages listing for Client object updates.
5.4. Retrieving Individual Clients đź”—
The URL to be used to send GET
requests for retrieving individual Client objects MUST be the cds_client_uri
provided in the Client object.
If a Server has optionally implemented OAuth’s Dynamic Client Registration Management Protocol, the value of cds_client_uri
MUST be the same as registration_client_uri
, and access tokens issued from either a client_credentials
grant with the scope client_admin
or the access token provided as the registration_access_token
MUST be valid access tokens to interact with the client retrieval endpoint (cds_client_uri
).
5.5. Modifying Clients đź”—
This specification requires that the procedure to modify Clients MUST follow OAuth’s Client Update Request section in Dynamic Client Registration Management Protocol.
The URL to be used to send PUT
requests for updating clients MUST be the cds_client_uri
provided in the Client object.
If a Server has optionally implemented OAuth’s Dynamic Client Registration Management Protocol, the value of cds_client_uri
MUST be the same as registration_client_uri
, and access tokens issued from either a client_credentials
grant with the scope client_admin
or the access token provided as the registration_access_token
MUST be valid access tokens to interact with the client endpoint.
Servers MUST allow Clients to intially update the following fields:
redirect_uris
client_name
client_uri
logo_uri
scope
scope
contacts
tos_uri
policy_uri
cds_status
cds_default_scope
cds_default_redirect_uri
cds_default_authorization_details
Servers MUST NOT allow clients to update the following fields:
client_id
- This value is immutable from when it was assigned upon Client registration.client_id_issued_at
- This value is immutable from when the Client initially registered.client_secret
- This value is NOT included in any Client object response, except for the initial Client registration request. Clients MUST use the Credentials API to manage client secrets.client_secret_expires_at
- This value is NOT included in any Client object response. Clients MUST use the Credentials API to discover when a client secret will expire.grant_types
- This list is determined by the Server based on thegrant_types_supported
described in the the Scope Descriptions.response_types
- This list is determined by the Server based on theresponse_types_supported
described in the the Scope Descriptions.token_endpoint_auth_method
- This is set by the Server based on thetoken_endpoint_auth_methods_supported
described in the the Scope Descriptions.cds_created
- This is a URL set by the Server.cds_modified
- This is a URL set by the Server.cds_client_uri
- This is a URL set by the Server.cds_server_metadata
- This is a URL set by the Server.cds_clients_api
- This is a URL set by the Server.cds_messages_api
- This is a URL set by the Server.cds_credentials_api
- This is a URL set by the Server.cds_grants_api
- This is a URL set by the Server.cds_server_provided_files_api
- This is a URL set by the Server.cds_status_options
- This is a list set by the Server.
For other fields, the Server MUST determine the validity of the submitted Client fields and reject with a 400 Bad Response if not all submitted fields are either the same as previously set, or invalid values for that field.
If a Client does not include a field that is included in the Client object, this indicates that the Client wishes to reset the value of that field to the Server default.
If a Server needs to asynchronously review and approve changes to any submitted Client object fields that have been submitted by the Client and are different from the current values, for valid update requests the Server MUST respond with a 202 Accepted
response, which indicates that the submission was accepted but not fully saved as completed yet.
Any fields that have not been synchronously updated as part of the request and response MUST remain in the response as their previous values, and the Server MUST add one or more entries to the listed Messages for the modified fields that need to be asynchronously reviewed and approved.
Clients MAY then use the Messages API to track the asynchronous review of the modification request.
If all submitted fields have been synchronously updated as part of the response, Servers MUST respond with a 200 OK
response.
6. Messages API đź”—
To facilitate automated communication and notificatiosn between Servers and Clients, this specification requires that official communication between Servers and Clients be performed using the Client Messages APIs. Servers MAY implement other means of communications for exchanging messages and notifications, such as email support, but they MUST also mirror any official communications that impact Client or Grant statuses, settings, or access using the Messages API.
The Messages API endpoints are authenticated using a Bearer access_token
obtained by the Client using OAuth’s client_credentials
grant process, where the client_id
used is for a Client that includes the client_admin
scope.
6.1. Message Object Format đź”—
Message objects are formatted as JSON objects and contain the following named values:
uri
- URL - (REQUIRED) Where to retrieve or modify this specific Message object.previous_uri
- URL ornull
- (REQUIRED) Where to find the previous Message to which this Message has been created as a reply.type
- ClientMessageType - (REQUIRED) The type of Message.read
- boolean - (REQUIRED) Whether the object has been marked as read by a Client. When the Server creates a Message, this value MUST befalse
by default, so that the Message appears in the unread list.creator
- string ornull
- (REQUIRED) If the Server created the Message, this value isnull
. If the Client created the Message, this value is the Client’sclient_id
.created
- datetime - (REQUIRED) When the Message was created.modified
- datetime - (REQUIRED) When the Message was last modified.status
- ClientMessageStatus - (REQUIRED) The current status of the Message.name
- string - (REQUIRED) A human-readable name of the Message. If the Messagetype
isnotification
,private_message
, orsupport_request
, this is the message subject.description
- string - (REQUIRED) A human-readable description of the Message. If the Messagetype
isnotification
,private_message
, orsupport_request
, this is the message body.updates_requested
- Array[ClientUpdateRequest] - (OPTIONAL) The list of values that a Client has requested to be updated. This field is required for Messages with atype
value offield_changes
orserver_request
.related_uri
- URL ornull
- (OPTIONAL) If the Messagetype
isnotification
orprivate_message
, this value is where the Client can find more information, if available. If the Messagetype
issupport_request
, this value is a relevant URL for which the Client is requesting technical support. If the Messagetype
isfield_changes
, this is where the Client can retrieve the object that has been requested to be modified. If the Messagetype
ispayment_request
, this is where the Client can submit their payment to the Server or if paid, a link to the payment receipt. If the Messagetype
isserver_request
, this is where the Client can find more information about what information is being requested by the Server.amount
- decimal - (OPTIONAL) If the Messagetype
ispayment_request
, this amount the Client needs to pay to satisfy the payment request.currency
- string - (OPTIONAL) If the Messagetype
ispayment_request
, this is the monetary currency for theamount
in ISO 4217 currency code.
6.2. Message Types đź”—
Message object type
values MUST be one of the following:
notification
- The Server is sending the Client at notification message that is relevant to the Client. This message is considered to be not individually tailored to the Client specifically, but instead directed to all relevant Clients.private_message
- The Server or Client is sending a private message to the opposite party. This message is considered to be individually tailored and relevant only to that Client or Server.support_request
- The Client is submitting a technical support request to the Server.field_changes
- This Message represents that the Client has submitted changes to field values in other API objects, listed in theupdates_requested
list, but these changes were not synchronously approved by the Server and need to be reviewed asynchronously by the Server. While the Client originally triggered this Message to be created by submitting field changes that need to be asynchronously reviewed, the Server is responsible for creating this Message, so thecreator
value isnull
.server_request
- The Server is requesting the Client submit a new Message of typeclient_submission
with the fields listed inupdates_requested
.client_submission
- The Client is submitting a response to aserver_request
to update one or more fields of a specific object. Both Clients and Servers MAY create these types of Message requests.payment_request
- The Server is requesting payment by the Client to complete a financial payment before the Client may proceed with either registration approval or completing actions listed in theupdates_requested
list.
6.3. Message Statuses đź”—
Message object status
values MUST be one of the following:
complete
- For Messages withtype
values ofnotification
,private_message
, orclient_submission
, thestatus
MUST be set ascomplete
. For Messages withtype
values ofsupport_request
,field_changes
,server_request
, orpayment_request
, this represents the Server has completed and approved or resolved the Client’s technical support request, field changes, submission, or payment.open
- For Messages withtype
values ofserver_request
orpayment_request
, this represents that the Client has not yet submitted a response to the Server’s submission or payment request.pending
- For Messages withtype
values ofsupport_request
,field_changes
,server_request
, orpayment_request
, this represents the Server has not yet completed it’s review of the Client’s technical support request, field changes, submission, or payment.rejected
- For Messages withtype
values offield_changes
,server_request
, orpayment_request
, this represents the Server has completed and rejected the Client’s requested field changes, submission, or payment.errored
- For Messages withtype
values offield_changes
,server_request
, orpayment_request
, this represents the Server encountered an issue while processing the Client’s field changes, submission, or payment. The Client is RECOMMENDED to submit asupport_request
Messages with therelated_uri
as the relevant errored Message’suri
.
6.4. Client Update Request Object Format đź”—
Client Update Request objects are formatted as JSON objects and contain the following named values:
field
- string - (REQUIRED) The field name of the field that is being requested to be updated. For Messages withtype
values offield_changes
, this is the name of the object’s field on the API. For Messages withtype
values ofserver_request
, this is the Server’s identifier for the submission being requested from the client.name
- string - (OPTIONAL) For Messages withtype
values ofserver_request
, this MUST be a human-readable name of the submission type being requested as the client.description
- string - (OPTIONAL) For Messages withtype
values ofserver_request
, this MUST be a human-readable description providing the Client with more information about what this submission request item is.submitted_uri
- URL - (OPTIONAL) For Messages withtype
values ofclient_submission
, this MAY be a URL that the Client is submitting as their response to the Server’sserver_request
, when the Server’s requested field is for a remote resource, such as an logo or binary file.previous_value
- various - (OPTIONAL) For Messages withtype
values offield_changes
, this MUST be the value of the field that the is being requested to be changed from.new_value
- various - (OPTIONAL) For Messages withtype
values offield_changes
, this MUST be the value of the field that the is being requested to be changed to.
6.5. Listing Messages đź”—
Clients may request to list Message objects that they have access to by making an HTTPS GET
request, authenticated with a valid Bearer access_token
scoped to the client_admin
scope, to the cds_messages_api
URL included in the Client Registration Response or Clients API. The Message listing request responses are formatted as JSON objects and contain the following named values.
outstanding
- Array[ClientMessage] - (REQUIRED) A list of Messages where thestatus
isopen
orpending
.outstanding_next
- URL ornull
- Where to request the next segment of the list of outstanding Messages. If no next segment exists (i.e. the requester is at the end of the list), this value isnull
.outstanding_previous
- URL ornull
- Where to request the previous segment of the list of outstanding Messages. If no previous segment exists (i.e. the requester is at the front of the list), this value isnull
.unread
- Array[ClientMessage] - (REQUIRED) A list of Messages where theread
isfalse
.unread_next
- URL ornull
- Where to request the next segment of the list of unread Messages. If no next segment exists (i.e. the requester is at the end of the list), this value isnull
.unread_previous
- URL ornull
- Where to request the previous segment of the list of unread Messages. If no previous segment exists (i.e. the requester is at the front of the list), this value isnull
.read
- Array[ClientMessage] - (REQUIRED) A list of Messages where theread
istrue
.read_next
- URL ornull
- Where to request the next segment of the list of read Messages. If no next segment exists (i.e. the requester is at the end of the list), this value isnull
.read_previous
- URL ornull
- Where to request the previous segment of the list of read Messages. If no previous segment exists (i.e. the requester is at the front of the list), this value isnull
.
Responses to outstanding_next
, outstanding_previous
, unread_next
, unread_previous
, read_next
, or read_previous
MUST be formatted the same as the initial Message listing, and MUST only include listings for the relevant next segment.
For example, if the Client requests a unread_next
, the Server’s response MUST have outstanding
and read
lists be empty lists ([]
).
Listings of Message objects MUST be ordered in reverse chronological order by modified
timestamp, where the most recently modified relevant Message MUST be first in each listing.
6.6. Creating Messages đź”—
Clients create new Messages by sending an authenticated HTTPS POST
request to the cds_messages_api
endpoint with the body of the request formatted a JSON object.
The fields included in JSON object MUST include the following:
previous_uri
- URL ornull
- If submitting a Message with atype
value ofclient_submission
, this value MUST be the Messageuri
that this Message is being submitted in response to (i.e. must have atype
value ofserver_request
). If submitting a Message with atype
value ofsupport_request
orprivate_message
, if the Client is responding to a previous Message, this value MUST be the Messageuri
of that Message. If submitting a Message with atype
value ofsupport_request
orprivate_message
that is not responding to another specific Message, this value MUST benull
.type
- ClientMessageType - This value MUST be one ofprivate_message
,support_request
, orclient_submission
.name
- string - If submitting a Message with atype
value ofclient_submission
, this value MUST be an empty string (""
). If submitting a Message with atype
value ofsupport_request
orprivate_message
, this value MUST be the subject line of the message.description
- string - If submitting a Message with atype
value ofclient_submission
, this value MUST be an empty string (""
). If submitting a Message with atype
value ofsupport_request
orprivate_message
, this value MUST be the body of the message.updates_requested
- Array[ClientUpdateRequest] - If submitting a Client Update with atype
value ofclient_submission
, this value MUST be a list of Client Update Request objects withfield
values matching thefield
values in the correspondingserver_request
Client Update Request objects, anddescription
orsubmitted_uri
values being the Client’s submission response to the Server’s request for thatfield
.related_uri
- URL ornull
- If submitting a Message with atype
value ofsupport_request
, this value MAY be a URL to the relevant API endpoint for the support request. If there is no relevant API endpoint, the Client MUST set this value asnull
.
Servers MUST reject requests with a 400 Bad Request
response when a Client submits an incomplete request or the submitted values are invalid.
For valid POST
requests from Clients, Servers MUST respond with a 201 Created
response with a JSON object of the complete newly created Message object.
When committing Messages created by Clients, Servers MUST populate the following fields in addition to the Client’s submitted fields:
uri
- URL - The endpoint where the Client can retrieve the newly created Message object.read
- boolean - Always set totrue
.creator
- string - Always set to the Client’sclient_id
.created
- datetime - Always set to the Server’s timestamp for when the Message was created.modified
- datetime - Always the same ascreated
.status
- ClientMessageStatus - Fortype
values ofprivate_message
orclient_submission
, this value MUST becomplete
. Fortype
values ofsupport_request
, this value MUST bepending
.
When Clients submit Messages with type
value of client_submission
, if the Message referenced in the previous_uri
has a status
of open
, then the Server MUST update the status
of that referenced Message to pending
, which indicates that the Client has submitted a response for Server review.
6.7. Modifying Messages đź”—
Clients may modify fields in a Messages object by sending an authenticated HTTPS PATCH
request to the Message uri
endpoint with the body of the request formatted a JSON object.
The fields included in JSON object are the fields the Client intends to modify with the submitted fields’ values.
If a field is not included in the PATCH
request, the Server MUST leave the field unmodified from its current value.
The following are fields that MAY be included in the PATCH
request, and modification MUST be supported by Servers:
read
- Servers MUST accept values oftrue
andfalse
from the Client.
If a Client wishes to modify a previously submitted Message of type client_submission
they created, the Client MUST create a new Message with the same previous_uri
value as the Message the Client is wishing to supersede.
Severs MUST process newer Messages created by the Client as overriding the Client’s previous submission.
If a Client wishes to amend a previously created Message of type private_message
or support_request
they created, the Client MUST create a new Message with the previous_uri
value set as the Message uri
for which they are wanting to amend.
Severs MUST consider newer Messages created by the Client as amending the Client’s previous support request or message.
7. Credentials API đź”—
To allow Clients to manage client_secret
values used for authentication to APIs, this specification requires that Server implement a Credentials API.
Servers MAY implement other means of managing Credentials, such as a web interface, but they MUST also mirror any Credentials managed by other means on this required Credentials API.
The Credentials API endpoints are authenticated using a Bearer access_token
obtained by the Client using OAuth’s client_credentials
grant process, where the client_id
used is for a Client that includes the client_admin
scope.
7.1. Credentials Object Format đź”—
Credentials objects are formatted as JSON objects and contain the following named values:
credential_id
- string - (REQUIRED) The unique identifier for the Credential on the Server’s system.uri
- URL - (REQUIRED) Where to retrieve, modify, or delete this specific Credential object.client_id
- string - (REQUIRED) Which Client this Credential belongs to.created
- datetime - (REQUIRED) When the Credential was created.modified
- datetime - (REQUIRED) When the Credential was last modified.type
- CredentialType - (REQUIRED) The type of credential.client_secret
- string - (OPTIONAL) A sufficiently random value generated by the Server that can be used by the Client to authenticate themselves when obtaining anaccess_token
from the Server’s OAuth token endpoint. This field MUST be included if thetype
isclient_secret
.client_secret_expires_at
- integer - (OPTIONAL) The timestamp at which theclient_secret
will expire, as defined in OAuth’s Client Information Response. If the Client object refrenced by theclient_id
has a status ofdisabled
, this value MUST be set to the time when the Client object was most recently disabled. This field MUST be included if thetype
isclient_secret
.
Other specifications MAY extend this set of fields to add additional Credential fields.
7.2. Credentials Types đź”—
Credential object type
values MUST be one of the following:
client_secret
- The Credential is a shared secret string string in theclient_secret
value on the Credential object.
Other specifications MAY extend this list to add additional Credential types.
7.3. Listing Credentials đź”—
Clients may request to list Credential objects that they have access to by making an HTTPS GET
request, authenticated with a valid Bearer access_token
scoped to the client_admin
scope, to the cds_credentials_api
URL included in the Client Registration Response or Clients API.
The Credential listing request responses are formatted as JSON objects and contain the following named values.
credentials
- Array[ScopeCredential] - (REQUIRED) A list of Credentials to which the requestingaccess_token
is scoped to have access. If no Credentials are accessible, this value is an empty list ([]
). If more than 100 sCredentials are available to be listed, Servers MAY truncate the list and use thenext
value to link to the next segment of the list of Credentials.next
- URL ornull
- Where to request the next segment of the list of Credentials. If no next segment exists (i.e. the requester is at the end of the list), this value isnull
.previous
- URL ornull
- Where to request the previous segment of the list of Credentials. If no previous segment exists (i.e. the requester is at the front of the list), this value isnull
.
Servers MUST support Clients adding any of the following URL parameters to the GET
request, which will filter the list of Credentials to be the intersection of results for each of the URL parameters filters:
credential_ids
- A space-separated list ofcredential_id
values for which the Servers MUST filter the Credentials.client_ids
- A space-separated list ofclient_id
values for which the Servers MUST filter the Credentials.after
- A datetime for which the Server MUST filter Credentials that were created after or on the datetime.before
- A datetime for which the Server MUST filter Credentials that were created before or on the datetime.
Listings of Credential objects MUST be ordered in reverse chronological order by modified
timestamp, where the most recently modified relevant Credential MUST be first in each listing.
For Credential objects in the listing that are added, removed, or modified by the Server or Client after initial registration, Servers MUST add a message to the listed Messages notifiying the Client that a Credential object has been added, removed, or modified. This creates a changelog in the Messages listing for Credential object updates.
7.4. Retrieving Individual Credentials đź”—
The URL to be used to send GET
requests for retrieving individual Credential objects MUST be the Credential uri
provided in the Credential object.
7.5. Creating Credentials đź”—
Clients create new Credentials by sending an authenticated HTTPS POST
request to the cds_credentials_api
endpoint with the body of the request formatted a JSON object.
The fields included in JSON object MUST include the following:
client_id
- string - This value is Client object’s identifier for which a new Credential object will be created.
Servers MUST reject requests with a 400 Bad Request
response when a Client submits an incomplete request or the submitted values are invalid.
For valid POST
requests from Clients, Servers MUST respond with a 201 Created
response with an updated JSON object of the created Credential object.
7.6. Modifying Credentials đź”—
Clients may modify fields in the Credentials API by sending an authenticated HTTPS PATCH
request to the Credential uri
endpoint with the body of the request formatted a JSON object.
The fields included in JSON object are the fields the Client intends to update with the submitted fields’ values.
If a field is not included in the PATCH
request, the Server MUST leave the field unmodified from its current value.
The following are fields that MAY be included in the PATCH
request, and modification MUST be supported by Servers:
client_secret_expires_at
- Servers MUST only accept valid timestamp values greater than or equal to the current time and less than or equal to the current value. When the current value is0
, indicating no expiration time, Severs MUST allow Clients to set a value of0
or any timestamp greater than or equal to the current time.
Servers MUST reject requests with a 400 Bad Request
response when fields are submitted that are not able to be modified by the Client or the submitted values are invalid.
If all submitted fields are valid and have been updated, the Server MUST respond with a 200 OK
response.
If a Client updates the client_secret_expires_at
of a Credential to be a timestamp equal to or less than the current time, the Server MUST assume the Credential is compromised and synchronously disable the Credential’s client_secret
from being used on the token endpoint and revoke any access_token
or refresh_token
values issued by the token endpoint as a result of using the now-disabled Credential.
Servers MAY, based on their own policies or discussion between the Client and Server, modify the client_secret_expires_at
arbitrarily.
Servers MUST NOT modify client_secret
values after they are created.
If the client_secret
is determined to be leaked or compromised, Servers MUST update the client_secret_expires_at
value to the current time or less, thus expiring the Credential.
8. Grants API đź”—
This specification requires Servers provide an API allowing Clients to view and edit OAuth user authorizations and client credentials grants (“Grants”) related to their registration.
These APIs are authenticated using a Bearer access_token
obtained by the Client using OAuth’s client_credentials
grant process, where the client_id
used is for a Client that includes the client_admin
scope.
8.1. Grant Object Format đź”—
Grant objects are formatted as JSON objects and contain the following named values:
grant_id
- string - (REQUIRED) The unique identifier for the Grant on the Server’s system.uri
- URL - (REQUIRED) A link to this specific Grant that can be used to retrieve or modify the individual Grant.replacing
- Array[URL] - (REQUIRED) If this Grant is superseding another Grant, this is the list of Granturi
values of the superseded Grants. If this grant is not superseding any other Grants, this value is an empty list ([]
).replaced_by
- Array[URL] - (REQUIRED) If this Grant has been superseded by other Grants, this is the list of Granturi
values of the superseding Grants. If no other Grants have superseded this Grant, this value is an empty list ([]
).parent
- URL ornull
- (REQUIRED) If this Grant represents an individual sub-authorization that is part of another Grant that required multiple authorizations, this is where to find the parent Grant. If this Grant is not a sub-authorization, this value isnull
.children
- Array[URL] - (REQUIRED) If this Grant represents a parent Grant that has multiple sub-authorizations underneath it, this is a list of Granturi
values for where to find the sub-authorizations. If this Grant does not have any sub-authorizations, this value is an empty list ([]
).created
- datetime - (REQUIRED) When the Grant was created.modified
- datetime - (REQUIRED) When the Grant was most recently modified. If the Grant has not been modified since creation, this is the same value ascreated
.not_before
- datetime ornull
- (REQUIRED) When a Grant that is for future access, Grant’sstatus
will be switched fromfuture
to another value. If the Grant is not for future access and access is available immediately upon creation, this value isnull
.not_after
- datetime ornull
- (REQUIRED) When a Grant has access that will expire in the future, this value indicates when the Grant’sstatus
will be switched toexpired
. If the Grant does not expire, this value isnull
.eta
- datetime ornull
- (REQUIRED) When a Grant has astatus
with the valuepending
, this value indicates an estimated time for when the status is expected to be switched to another value. If the Grant’sstatus
is notpending
this value isnull
.expires
- datetime ornull
- (REQUIRED) When the Grant will expire and access will be removed by the Server. If the Grant is to continue indefinitely, this value isnull
.status
- GrantStatus - (REQUIRED) The current Grant Status of the Grant.client_id
- string - (REQUIRED) Which Client for which this Grant is issued.cds_client_uri
- URL - (REQUIRED) Where to retrieve using the Clients API the Client for which the Grant is issued.scope
- string - (REQUIRED) The scopes for which this Grant has issued access.authorization_details
- Array[OAuth AuthorizationDetail] - (REQUIRED) Any authorization details scopes that are granted in addition to this object’sscope
value. If no authorization details scopes are configured in addition to thescope
string, this value is an empty array ([]
). If thetype
field of an authorization detail object in this array is the same as a value in thescope
string, the authorization detail object replaces the scope with additional more refined access details for the scope.receipt_confirmations
- Array[string] - (REQUIRED) For Grants with scopes that can be obtained via user authorization (grant_types
containsauthorization_code
), this is a list of receipt confirmation codes that were provided to the end users who authorized the access. If no receipt was provided or the Grant did not get issued viaauthorization_code
then this value is an empty list ([]
).enabled_scope
- string - For Grants where access has been partially granted, but some access is still disabled, this value is thescope
that has been enabled by the server. For Grants where access has been fully granted, this value is the same as thescope
value. For Grants that have had their access removed (e.g.disabled
), this value is an empty string (""
).enabled_authorization_details
- Array[OAuth AuthorizationDetail] - For Grants where access has been partially granted, but some access is still disabled, this value is theauthorization_details
that has been enabled by the server. For Grants where access has been fully granted, this value is the same as theauthorization_details
value. For Grants that have had their access removed (e.g.disabled
), this value is an empty list ([]
).sub_authorization_scopes
- Array[string] - (REQUIRED) For Grants that require sub-authorizations where users must provide additional authorization to enable access, this is the outstanding list ofscope
values that have yet to be authorized individually by users.
8.2. Grant Statuses đź”—
Grants object status
values MUST be one of the following:
active
- The Grant is active and access for the features and data specified in thescope
orauthorization_details
is currently enabled. For Grants that provide access to data APIs that are being regularly updated, this status also indicates that the Server is currently on schedule to provide the expected ongoing data updates.future
- The Grant will be made in the future, and the Client should check thenot_before
value for when the Grant will have its status switched toactive
.pending
- The Grant has been create and is valid, but the Server is still processing or reviewing the Grant and the status will be changed to another status at approximately the time provided in the Grant’seta
value. While a Grant’s status ispending
, Servers MUST provide access to the granted scope’s features or data as the Server processes and the features or data becomes available.partial
- The Grant was submitted originally with thescope
andauthorization_details
values, but the Server has limited the Client’s access a subset of the Grant’sscope
. The enabled access is listed in theenabled_scope
andenabled_authorization_details
values.needs_authorization
- The Grant has been created, but access is limited to theenabled_scope
andenabled_authorization_details
until a user authorizes the listedscope
andauthorization_details
values using an authorization URL with acds_grant_id
parameter of thisgrant_id
.needs_sub_authorizations
- The Grant has been created, but access is limited to theenabled_scope
andenabled_authorization_details
until user sub-authorizations, listed in thesub_authorization_scopes
value, are granted using an authorization URL with acds_parent_id
parameter of thisgrant_id
.disabled
- The Grant has been indefinitely disabled by the Server, and the Client SHOULD NOT expect the Grant’s status to be updated in the future.suspended
- The Grant has been temporarily disabled by the Server or user who authorized access, and the Client SHOULD expect the Grant’s status to be updated in the future.revoked
- For Grants with scopes that can be obtained via user authorization (grant_types
containsauthorization_code
), this status means the user has revoked access.closed
- The Grant has been revoked by the Client via the Modifying Grants API.expired
- The Grant has expired and access has been removed. The Grant’snot_after
value indicates when the Grant’s access was removed and the Grant is considered expired.delayed
- For Grants that provide access to data APIs that are being regularly updated, this status indicates that the data being provided is behind schedule and will be updated when the Server resolves its internal delay issues.stopped
- For Grants that provide access to data APIs that are being regularly updated, this status indicates that the data being provided has stopped being updated either by the Server or the user who originally authorized the access. Access to existing data is still available, but the Client should not expect updates to the data being provided.errored
- The Server has encountered an internal error for this Grant, and Client access cannot be confirmed by the Server.
Grant status
values of future
, disabled
, suspended
, revoked
, closed
, and expired
indicate that access to all features and data that were accessible via this Grant are no longer accessible.
8.3. Listing Grants đź”—
Clients may request to list Grant objects that they have access to by making an HTTPS GET
request, authenticated with a valid Bearer access_token
scoped to the client_admin
scope, to the cds_grants_api
URL included in the Client Registration Response or Clients API.
The Grant listing request responses are formatted as JSON objects and contain the following named values.
grants
- Array[Grant] - (REQUIRED) A list of Grants to which the requestingaccess_token
is scoped to have access. If no Grants are accessible, this value is an empty list ([]
). If more than 100 Grants are available to be listed, Servers MAY truncate the list and use thenext
value to link to the next segment of the list of Grants.next
- URL ornull
- Where to request the next segment of the list of Grants. If no next segment exists (i.e. the requester is at the end of the list), this value isnull
.previous
- URL ornull
- Where to request the previous segment of the list of Grants. If no previous segment exists (i.e. the requester is at the front of the list), this value isnull
.
Servers MUST support Clients adding any of the following URL parameters to the GET
request, which will filter the list of Grants to be the intersection of results for each of the URL parameters filters:
statuses
- A space-separated list ofstatus
values for which the Servers MUST filter the Grants.client_ids
- A space-separated list ofclient_id
values for which the Servers MUST filter the Grants.cds_client_uris
- A space-separated list ofcds_client_uri
values for which the Servers MUST filter the Grants.scopes
- A space-separated list ofscope
values for which the Server MUST filter the Grants, where the includedscope
values are values within the Grantscope
(space separated) or as atype
value in theauthorization_details
list.receipt_confirmations
- A space-separated list of receipt confirmation codes for which the Server MUST filter the Grants.after
- A datetime for which the Server MUST filter Grants that were created after or on the datetime.before
- A datetime for which the Server MUST filter Grants that were created before or on the datetime.
Listings of Grant objects MUST be ordered in reverse chronological order by modified
timestamp, where the most recently updated relevant Grant MUST be first in each listing.
8.4. Retrieving Individual Grants đź”—
The URL to be used to send GET
requests for retrieving individual Grant objects MUST be the Grant uri
provided in the Grant object.
8.5. Modifying Grants đź”—
Clients may modify fields in the Grants API by sending an authenticated HTTPS PATCH
request to the Grant uri
endpoint with the body of the request formatted a JSON object.
The fields included in JSON object are the fields the Client intends to update with the submitted fields’ values.
If a field is not included in the PATCH
request, the Server MUST leave the field unmodified from its current value.
The following are fields that MAY be included in the PATCH
request body, and modification MUST be supported by Servers:
status
- Servers MUST only accept a value ofclosed
from the Client.scope
- Servers MUST evaluate the updated scope for whether another user authorization is required. Servers MUST not require another user authorization if the updated scope is a reduction in scope of access (e.g. removal of a scope value from the scope string). If a new user authorization or sub-authorizations are required, the Server MUST update thestatus
to one ofneeds_authorization
orneeds_sub_authorizations
and update theenabled_scope
to be the value of the current scope for which the Client is allowed access.authorization_details
- Servers MUST evaluate the updated authorization details for whether another user authorization is required. Servers MUST not require another user authorization if the updated scope is a reduction in scope of access (e.g. removal of a scope value from the scope string). If a new user authorization or sub-authorizations are required, the Server MUST update thestatus
to one ofneeds_authorization
orneeds_sub_authorizations
and update theenabled_authorization_details
to be the value of the current authorization details for which the Client is allowed access.
Servers MUST reject requests with a 400 Bad Request
response when fields are submitted that are not able to be modified by the Client or the submitted values are invalid.
For valid PATCH
requests from Clients, Servers MUST respond with a 200 OK
response with an updated JSON object of the complete current Grant object.
If a Server needs to asynchronously review and approve changes to any submitted Grant object fields that have been submitted by the Client and are different from the current values, for valid modification requests the Server MUST update the Grant’s status
to pending
in the response.
Additionally, if the scope
or authorization_details
has been updated, the Server MUST update the enabled_scope
and enabled_authorization_details
to reflect for what the Client currently has access while the Grant is pending.
9. Server-Provided Files API đź”—
This specification defines an API by which Servers MAY provide an access to arbitrary files to Clients to download.
These APIs are authenticated using a Bearer access_token
obtained by the Client using OAuth’s client_credentials
grant process, where the scope of the access token is grant_admin
with authorizatin_details
entries listing grant_id
values that are for Grants that have the server_provided_files
scope.
9.1. Server-Provided Files Object Format đź”—
Server-Provided File objects are metadata for arbitrary files made accessible by the Server and are formatted as JSON objects containing the following named values:
file_id
- string - (REQUIRED) The unique identifier for the Server-Provided File on the Server’s system.created
- datetime - (REQUIRED) When the Server-Provided File was created.modified
- datetime - (REQUIRED) When the Server-Provided File was most recently modified. If the Server-Provided File has not been modified since creation, this is the same value ascreated
.mime_type
- string - (REQUIRED) The MIME type of the file.size
- integer - (REQUIRED) The size of the file in bytes.name
- string - (REQUIRED) The file name, including any file extension.description
- string - (REQUIRED) A description of the file. If no description is provided by the Server, this is an empty string (""
).download_uri
- URL - (REQUIRED) A link to the raw file being made accessible by the Server. Servers MUST authenticate this download endpoint using the same authentication requirements as the rest of the Server-Provided Files API.
9.2. Listing Server-Provided Files đź”—
Clients may request to list Server-Provided File objects that they have access to by making an HTTPS GET
request, authenticated with a valid Bearer access_token
scoped to the client_admin
scope, to the cds_server_provided_files_api
URL included in the Client Registration Response or Clients API.
The Server-Provided File listing request responses are formatted as JSON objects and contain the following named values.
files
- Array[ServerProvidedFile] - (REQUIRED) A list of Server-Provided File objects to which the requestingaccess_token
is scoped to have access. If no Server-Provided File objects are accessible, this value is an empty list ([]
). If more than 100 Server-Provided File objects are available to be listed, Servers MAY truncate the list and use thenext
value to link to the next segment of the list of Server-Provided File objects.next
- URL ornull
- Where to request the next segment of the list of Server-Provided File objects. If no next segment exists (i.e. the requester is at the end of the list), this value isnull
.previous
- URL ornull
- Where to request the previous segment of the list of Server-Provided File objects. If no previous segment exists (i.e. the requester is at the front of the list), this value isnull
.
Listings of Server-Provided File objects MUST be ordered in reverse chronological order by modified
timestamp, where the most recently updated relevant Server-Provided File object MUST be first in each listing.
11. Extensions đź”—
TODO
12. Examples đź”—
TODO
13. Security Considerations đź”—
This specification describes a protocol by which a utility or other entity (a Server) can allow third parties (Clients) to register and obtain privileged access to the Server’s offered capabilities and data. Because the functionality described in this specification enables access to private Server functionality and data, Servers MUST follow industry cybersecurity best practices when securing their implementations of this specification to prevent unintended or inadvertent access to privileged functionality or data to Clients who are not authorized. These best practices include requiring HTTPS for API endpoints using the latest widely adopted encryption standards, undergoing regular security audits and penetration tests, and internally requiring security-focused process controls and data handling procedures.
TODO: Other security considerations
13.1. Restricted Access đź”—
For unauthenticated endpoints (Authorization Server Metadata, Client Registration Process), while Servers can add rate limiting configurations to protect their systems from being overwhelmed with requests, Servers MUST NOT add anti-bot blocking measures (e.g. captchas) that prevent automated requests from other systems. The functionality described in this specification is intended to be able to be integrated in other platforms to allow those platforms to automate interactions with Servers on their users’ behalf.
If Authorization Server Metadata is referenced in a public CDSC-WG1-01 Server Metadata endpoint, then the Authorization Server Metadata and Client Registration Process must also be public.
Servers that wish to restrict access of by-default unauthenticated endpoints to certain Clients MUST configure well established authentication processes for Clients to ensure that only the approved Clients may access the restricted endpoint. This specification does not describe specifically how Servers will authenticate Clients for by-default unauthenticated endpoints, as these restricted access protocols are context dependent. For example, if a Server providing a private Client Registration endpoint as part of an existing logged in portal, then they can use that logged in portal’s session cookie to authenticate Client requests to the registration endpoint.
For authenticated endpoints (Clients API, Messages API, Credentials API, Grants API), Servers MUST authenticate requests using OAuth’s Authorization Request Header Field with access tokens obtained using the OAuth’s Issuing an Access Token process.
13.2. Rate Limiting đź”—
For unauthenticated endpoints (Authorization Server Metadata, Client Registration Process), Servers SHOULD configure rate limiting restrictions so that bots and misconfigured scripts will not flood and overwhelm the endpoints with requests, while still allowing legitimate and low-volume automated requests have access to the endpoints.
For authenticated endpoints (Clients API, Messages API, Credentials API, Grants API), Servers SHOULD configure rate limiting by Client and Credential to ensure that individual Clients do not overwhelm Servers with authenticated API requests. Additionally, Servers SHOULD configure rate limiting for unauthenticated or failed authentication requests to authenticated API endpoints to prevent brute force attempts to gain access to authenticated APIs.
14. References đź”—
TODO
15. Acknowledgments đź”—
The authors would like to thank the late Shuli Goodman, who was the Executive Director of LFEnergy, for her incredible leadership in initially organizing the Carbon Data Specification.
16. Authors’ Addresses 🔗
Daniel Roesler
UtilityAPI
Email: daniel@utilityapi.com
URI: https://utilityapi.com/