Skip to content

Permission Records

OAuth Issuers must provide an additional endpoint to fetch information about the underlying Permission granted by the end user. Permission Records and the Evidence URL within it contain:

  • Who provided the permission - e.g. a logged-in user
  • On whose behalf the permission is provided - e.g. the SME
  • When was the permission provided
  • How the permission was provided - e.g., the app version on such-and-such a device
  • Which data processor has the permission
  • For what purpose the specific permission record applies to
  • How the purpose was described to the user
  • How long the permission is valid for

Note: This document uses US English. To align with W3C and other prevalent standards, IB1 uses US English in its technical specifications and technical documentation.

Permission Record properties

All specified fields except revoked MUST be included.

Date and time fields are ISO8601 dates with 'Z' denoting UTC.

  • oauthIssuer - the URL of the OAuth Issuer
  • client - the URL of the Application in the Directory
  • license - the URL of the License under which data is accessed (the OAuth scope)
  • account - an opaque identifier for the end user or account holder. The value is NOT required to be the same in every Permission Record relating to an end user.
  • lastGranted - when permission was last granted by the end user.
  • expires - when the permission expires, and will need to be explicitly renewed by the end user.
  • evidence - the Evidence URL which may be used by the user to see details of how permission was granted.
  • revoked - when permission was revoked by the end user. This field must not be present if the permission has not been revoked. To avoid issues with variations in server time between systems, the presence of a timestamp for this field should be taken to mean that permission has been revoked
  • dataAvailableFrom - the earliest date for which historical data will be available through the API. The client must not infer additional information from this date, such as the age of the end user's account or whether data exists for that period. This is provider and data source dependent, and could be:
    • The date when permission was first provided.
    • The date the end user's account was opened at the provider.
    • The date the end user first occupied the premises where a meter is installed.
  • tokenIssuedAt - when the token was issued. (Several refresh tokens will be issued during the lifetime of the permission.)
  • tokenExpires - the token expiration date, which must not be later than the expires value of the permission

This specification may be used with additional specifications which extend this API to provide structured data about the permission log and evidence that the user has authority to give that permission. This data is highly variable and dependent on the market, the type of end user, the data source, and the data provider. When a Trust Framework only uses this base specification, this information is only available in a human-readable form as a web page at the Evidence URL.

Permission Endpoint

OAuth Issuers provide an endpoint to retrieve a Permission Record. A client makes a POST request with a refresh token in the token parameter to this URL, which returns a JSON formatted response with the Permission Record in the permission property.

Refresh tokens may be used to retrieve Permission Records for at least 12 months after token expiration or revocation, allowing applications to access details of expired permissions.

Access tokens must not be accepted.

Permission Endpoint discovery

A client discovers the URL of the Permission endpoint from the ib1_permission_endpoint field in the OAuth Issuer's Authorization Server Metadata.

Evidence URLs

Evidence URLs are URLs which contain an unguessable identifier and may be viewed by a web browser. These URLs:

  • use https with a public CA
  • do not require any authentication (other than the unguessable identifier in the URL)
  • will present all the evidence, formatted as an HTML document capable of displaying in mobile portrait orientation with 320px width when the user clicks “show evidence”
  • is not required to display the contents of identity documents or similar materials provided by the user, only the type or form of evidence obtained
  • where data is provided by remote data collection from installed equipment (for example, energy Smart Meters), how the equipment ownership was established, and what permission was granted for data sharing
  • will contain information about all previous grants of permission and renewals for the specific data consumer associated with the URL, not just for the current token.

If an Evidence URL is included in the evidence property of the record, the provider asserts that they have obtained permission from the end user and hold all the necessary evidence.

Example request and response

POST /issuer/permission
token=AvbmC1RbCDryaYSG2IxaOAQWmy6UWCN7OAfYCTBko

{
  "permission": {
    "oauthIssuer": "https://api.example.com/issuer",
    "client": "https://directory.core.pilot.trust.ib1.org/member/28364528",
    "license": "https://registry.core.pilot.trust.ib1.org/scheme/electricity/license/energy-consumption-data/2024-12-05",
    "account": "6qIO3KZx0Q",
    "lastGranted": "2024-03-31T23:30Z",
    "expires": "2025-03-31T23:30Z",
    "evidence": "https://api.example.com/evidence/tkDMf6lkNl",
    "revoked": "2024-07-01T12:34Z",
    "dataAvailableFrom": "2021-07-12T00:00Z",
    "tokenIssuedAt": "2024-06-30T23:30Z",
    "tokenExpires": "2024-09-30T23:30Z"
  }
}