N3Rgy Authentication

generated: '2026-07-27'
method: searched
source: openapi/n3rgy-customer-service-api-v2-openapi.yaml
docs: https://customer-api-user-manuals.data.n3rgy.com/authentication/
docs_sandbox: https://customer-api-user-manuals.data.n3rgy.com/sandbox-authentication/
description: >-
  n3rgy authenticates with a single API key in the x-api-key header — and then
  authorises in two further layers that the OpenAPI cannot express. Layer 2 is
  end-customer CONSENT, validated server-side against the Home Area Network
  behind the supplied MPxN. Layer 3 is a per-account permission to change meter
  update frequencies. All three failures surface as HTTP 403 with different
  messages, so a client cannot distinguish "bad key" from "no consent" by status
  code alone — only by the message string.
summary:
  types:
  - apiKey
  api_key_in:
  - header
  oauth2_flows: []
  oidc: false
  mtls: false
  authorization_layers: 3
schemes:
- name: ApiKeyAuth
  type: apiKey
  in: header
  parameter: x-api-key
  x-amazon-apigateway-api-key-source: HEADER
  sources:
  - openapi/n3rgy-customer-service-api-v2-openapi.yaml
  applies_to: 25 of 26 operations

key_provisioning:
  self_serve: false
  live: >-
    "Access to the Customer Service API must be enabled for the user's live API
    key by the n3rgy data backoffice."
  sandbox: >-
    "Access to the Customer Service API Sandbox must be enabled for the user's
    sandbox API key by the n3rgy data backoffice."
  steps:
    - Read the developer guide anonymously — no login required.
    - Complete the business sign-up form at https://data.n3rgy.com/business-sign-up (free sandbox tier).
    - Contact n3rgy to have the live key enabled by the back office.
    - Obtain end-customer consent per property before any consent-bearing endpoint returns data.
  environment_separation: by hostname, not by key prefix (see sandbox/n3rgy-sandbox.yml)
  key_prefixes: none published
  rotation_policy: not published

authorization_layers:
  - layer: 1
    name: API key
    mechanism: x-api-key header
    failure: 403 "User is not authorized to access this resource with an explicit deny."
    applies_to: all operations except RetrieveReadingTypeData
  - layer: 2
    name: consent verification
    mechanism: >-
      Server-side check that an ACTIVE consent exists for the HAN identified by
      the supplied MPxN. Consent is granted and withdrawn by the occupant through
      the n3rgy Consumer Portal (https://data.n3rgy.com/consumer-login), not
      through this API.
    failures:
      - 403 "Consent for the given MPxN not found."
      - 403 "Consent for the given MPxN does not have update frequencies set."
      - 403 "Consent for the property of the target meter not found."
    applies_to:
      - RetrieveConsentedMPxNUtilities
      - RetrieveDataTypesForUtility
      - RetrieveDataUpdateFrequencies
      - RetrieveDataForReadingType
      - generateFetchNowRequest
      - SetMeterUpdateFrequency
  - layer: 3
    name: frequency-change permission
    mechanism: A per-customer flag allowing update-frequency changes.
    failure: 403 "User is not authorized to access this resource with an explicit deny."
    applies_to:
      - SetMeterUpdateFrequency
      - SetDefaults
      - ResetAllUpdateFrequencies

key_only_operations:
  note: Authenticated by x-api-key alone, with no consent check.
  operations:
    - RetrieveConsentedMPxNs
    - RetrieveMPxNAvailability
    - mpxnFromAddress
    - ReadInventory
    - GetPushNotificationConfiguration
    - EditPushNotificationConfiguration
    - DeletePushNotificationConfiguration
    - RetrievePushNotificationStatus

unsecured_operations:
  - operationId: RetrieveReadingTypeData
    path: POST /internal/{mpxn}/{utility}/{readingType}
    note: >-
      Declares an EMPTY security array in the OpenAPI (no ApiKeyAuth). Almost
      certainly an internal endpoint fronted by other controls — flagged here as a
      contract inconsistency worth raising with the provider, not as a claim that
      the endpoint is publicly callable. The host answers 403 to anonymous
      callers.

not_supported:
  oauth2: >-
    No oauth2 securityScheme; no /.well-known/oauth-authorization-server on any
    host. Therefore no scopes/ artifact is emitted — there is no scope surface.
  openid_connect: >-
    No /.well-known/openid-configuration is served anywhere (401 on
    consumer-api.data.n3rgy.com, SPA HTML shell on data.n3rgy.com).
  mutual_tls: not declared
  http_basic_bearer: not declared

history:
  - >-
    n3rgy data 1.x authenticated with the Authorization header. n3rgy data 2.0
    migrated every endpoint to X-API-KEY ("With n3rgy data 2.0, all new endpoints
    will be using X-API-KEY as header parameter instead of the old authorization
    header." — developer guide Overview).
  - >-
    The legacy consumer API authenticated with the IHD MAC address of the
    property's in-home display. That API has been withdrawn.

cross_references:
  conventions: conventions/n3rgy-conventions.yml
  errors: errors/n3rgy-problem-types.yml
  sandbox: sandbox/n3rgy-sandbox.yml
  well_known: well-known/n3rgy-well-known.yml