> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auth.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Register consumer consent

> <Warning>No idea how/if this works or even why it's here as specific customer tariffs are now out of scope</Warning>

Completes consumer consent registration after the OAuth 2.0 Authorisation Code
flow. The supplier resolves consumer identity from the token, records consent
against the MPXN, and returns a `registration_id` for managing the relationship.

Consent can be granted for a one-off access or open-endedly until revoked.




## OpenAPI

````yaml /tariff-interop/api/openapi-tariff.yaml post /v1/consent
openapi: 3.1.0
info:
  title: Tariff Interoperability API
  version: 0.1.1.AE
  description: >
    The Tariff Interoperability (TI) API lets Energy Smart Appliances,
    optimisers, and

    third-party services access standardised electricity tariff pricing data
    directly from

    GB energy suppliers. It is defined under the Retail Energy Code (REC) and
    mandated by

    the Smart Secure Electricity Systems (SSES) Programme.


    ## Two tiers of access


    | Tier | Who can use it | Auth required |

    |------|---------------|---------------|

    | **Public Tariff Pricing Data** | Any TI User | None |

    | **Consumer Specific Tariff Information** | Registered TI Users (RTI Users)
    with active consumer consent | OAuth 2.0 |
  contact:
    name: Auth Energy
    email: contact@auth.energy
  license:
    name: |
      © 2025 Retail Energy Code Company Ltd v0.1.0.
      All modifications and improves published © 2026 Auth Energy Ltd
    url: https://auth.energy/
servers:
  - url: https://register.tariff.interop
    description: >
      Central TI Register hosted by RECCo. Serves the `/v1/suppliers` and
      `/v1/users`

      endpoints only. The `v1` path prefix identifies the API version.
  - url: https://example-supplier.co.uk
    description: >
      Placeholder for a TI Energy Supplier's own hosted API. Each supplier runs
      their

      own instance at a URL they register with RECCo — discover it from `GET
      /suppliers`.

      Serves all `/v1/tariff`, `/v1/consent`, `/v1/webhook`, `/v1/report`, and
      outbound webhook endpoints.
security: []
tags:
  - name: Registry
    description: >-
      Discover active suppliers and registered third-party users. Served by the
      central RECCo register. No authentication required for public data.
  - name: Tariffs
    description: >-
      Retrieve tariff listings and full pricing detail from a specific supplier.
      No authentication required.
  - name: Consumer Tariffs
    description: >-
      Retrieve tariff data tied to a specific consumer metering point. Requires
      OAuth 2.0 and active consumer consent.
  - name: Consent
    description: >-
      Register and revoke consumer consent linking a metering point to an RTI
      User via the OAuth 2.0 Authorisation Code flow.
  - name: Webhooks
    description: >-
      Manage webhook endpoints and receive push notifications when tariff data
      or consent state changes.
  - name: Reporting
    description: >-
      Submit periodic performance assurance metrics to RECCo (supplier
      obligation).
paths:
  /v1/consent:
    post:
      tags:
        - Consent
      summary: Register consumer consent
      description: >
        <Warning>No idea how/if this works or even why it's here as specific
        customer tariffs are now out of scope</Warning>


        Completes consumer consent registration after the OAuth 2.0
        Authorisation Code

        flow. The supplier resolves consumer identity from the token, records
        consent

        against the MPXN, and returns a `registration_id` for managing the
        relationship.


        Consent can be granted for a one-off access or open-endedly until
        revoked.
      operationId: registerConsent
      requestBody:
        required: false
        description: No body required. Consumer identity is resolved from the OAuth token.
        content:
          application/json:
            schema:
              type: object
              description: Empty body — consumer identity is derived from the bearer token.
      responses:
        '200':
          description: >-
            Consent registered. Returns the registration ID and in-scope
            metering points.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - registration_id
                      - tariffs
                    properties:
                      registration_id:
                        type: string
                        format: uuid
                        description: >-
                          UUID uniquely identifying this consent grant. Use this
                          to revoke consent later.
                        example: f47ac10b-58cc-4372-a567-0e02b2c3d479
                      tariffs:
                        type: array
                        minItems: 1
                        description: MPXN / tariff ID pairs covered by this consent grant.
                        items:
                          type: object
                          required:
                            - mpxn
                            - tariff_id
                          properties:
                            mpxn:
                              $ref: '#/components/schemas/Mpxn'
                            tariff_id:
                              $ref: '#/components/schemas/TariffId'
              example:
                data:
                  registration_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
                  tariffs:
                    - mpxn: '1012345678901'
                      tariff_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - oauth2AuthCode:
            - tariff:register
      servers:
        - url: https://example-supplier.co.uk
          description: TI Energy Supplier API
components:
  schemas:
    Mpxn:
      type: string
      maxLength: 13
      description: >-
        Meter Point Administration Number (MPAN) or Meter Point Reference Number
        (MPRN).
      example: '1012345678901'
    TariffId:
      type: string
      format: uuid
      pattern: ^trf_[0-9a-f]{32}$
      description: >
        Compact UUID generated by the supplier uniquely identifying a set of
        tariff pricing data prefixed with `trf_`.

        A single display name may map to multiple tariff IDs where a supplier
        prices

        differently by payment method or region.
      example: trf_a1b2c3d4e5f67890abcdef1234567890
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: tariff_not_found
        message:
          type: string
          description: Human-readable error description.
          example: No tariff found for the given tariff_id and supplier MPID.
        details:
          type: string
          description: Additional context to help diagnose the issue.
          example: >-
            tariff_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 does not exist for
            supplier SEBD.
  responses:
    BadRequest:
      description: >-
        400 — Request does not match the required format or references an
        out-of-scope tariff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: 401 — Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: 500 — Unexpected server error. Retry within the 72-hour buffer window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2AuthCode:
      type: oauth2
      description: >
        OAuth 2.0 Authorisation Code flow for RTI User authentication and
        consumer consent.

        Each supplier operates its own OAuth server. In production, substitute
        the

        placeholder host with the relevant `url` from the Supplier Register.

        OpenAPI does not permit URI templates in security scheme URLs, so a
        placeholder

        is used here.
      flows:
        authorizationCode:
          authorizationUrl: https://example-supplier.co.uk/oauth2/authorize
          tokenUrl: https://example-supplier.co.uk/oauth2/token
          scopes:
            tariff:read:consumer: Read consumer-specific tariff data for consented metering points.
            tariff:register: Register and revoke consumer consent relationships.
            tariff:webhook: Register and manage webhook endpoints.

````