# OpenADR Alliance

> The OpenADR Alliance is a San Ramon, California membership corporation that develops, certifies and promotes OpenADR — the open information-exchange model utilities, ISOs/RTOs, aggregators and device makers use to automate demand response and dispatch distributed energy resources. It is a standards body, not a service operator. OpenADR 3 is defined entirely by an OpenAPI 3.0 contract covering programs, events, reports, subscriptions, VENs and resources, secured with OAuth 2.0 client credentials. The Alliance hosts no API: every implementer (a utility, aggregator or vendor VTN) stands up its own base URL.

Generated by API Evangelist on 2026-07-27 (method: generated — https://www.openadr.org/llms.txt returned 404).

## What this is and is not

- There is **no Alliance-hosted API and no baseURL**. Do not attempt to call an openadr.org endpoint. The specification's `servers[]` entry is a reference base path (`http://localhost:8081/openadr3` in 3.0.x) or a SwaggerHub auto-mock (`https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0` in 3.1.x) — neither is a production endpoint.
- The **OpenAPI YAML is the normative reference** for OpenADR 3 and supersedes any statement in the other documents.
- The Alliance publishes **no first-party SDK**; its canonical GitHub organisation (github.com/oadr3-org) has zero public repositories. Third-party libraries exist.
- The specifications are **license-free but copyrighted**; the public route is a registration form that emails download links.

## Roles

- **VTN** (Virtual Top Node) — the server side. Publishes programs and events, receives reports. Run by a utility, ISO/RTO, aggregator or building management system.
- **VEN** (Virtual End Node) — the client side. Subscribes to programs and events, writes reports for the resources it manages.
- **BL** (Business Logic client) — the VTN-side client that writes programs and events. Distinguished from a VEN by the OAuth scopes it may request.

## APIs

- [OpenADR 3 API](https://www.openadr.org/specification): RESTful third generation of the OpenADR protocol. 45 operations in 3.1.1 across programs, events, reports, subscriptions, vens, resources, auth and MQTT notifiers.

## Specs

- [OpenADR 3.1.1 OpenAPI](openapi/openadr-3-1-1-openapi.yaml): current development release, 45 operations, 9 tag groups, 9 OAuth scopes.
- [OpenADR 3.1.0 OpenAPI](openapi/openadr-3-1-0-openapi.yaml): latest released version, 45 operations. Not backwards compatible with 3.0.1.
- [OpenADR 3.0.1 OpenAPI](openapi/openadr-3-0-1-openapi.yaml): 31 operations. Adds the notifyEvent webhook callback.
- [OpenADR 3.0.0 OpenAPI](openapi/openadr-3-0-0-openapi.yaml): initial OpenADR 3 release, 31 operations.
- [Notifications AsyncAPI 3.0.0](asyncapi/openadr-alliance-notifications-asyncapi.yml): API Evangelist derivation of the webhook + MQTT event surface. Not a normative Alliance artifact.
- [Enumeration JSON Schemas](json-schema/_index.yml): the six enumeration schemas the Alliance ships with 3.1.1 — event interval payloads, report payloads, program attributes, VEN/resource attributes, reading types, units.

## Authentication

- OAuth 2.0 client credentials against the VTN's own `POST /auth/token`; JWT bearer on every other call.
- `GET /auth/server` returns the token endpoint URL — the OpenADR analogue of RFC 8414 discovery. There is no `/.well-known/` document on any Alliance host.
- Scopes are role-encoded: `read_all` (BL only), `read_ven_objects`, `read_targets`, `read_bl`, `write_programs` (BL only), `write_events` (BL only), `write_reports` (VENs only), `write_subscriptions`, `write_vens`.
- [Authentication profile](authentication/openadr-alliance-authentication.yml) · [OAuth scopes](scopes/openadr-alliance-scopes.yml)

## Conventions an agent must know

- **Pagination** is `skip` + `limit`, server-capped at `limit=50`, responses are bare JSON arrays with no total and no next link.
- **Idempotency is not supported.** There is no `Idempotency-Key`. A retried `POST /events` creates a second event — and events dispatch grid load. Read before you re-create.
- **Errors** use the Zalando problem schema (RFC 7807 member set: type, title, status, detail, instance) but are served as `application/json`, not `application/problem+json`.
- **No rate-limit contract** and no 429 response anywhere in the specification.
- **Datetimes** are RFC 3339; `0001-01-01T00:00:00` may mean "now". **Durations** are ISO 8601; `P9999Y` may mean infinity.
- [Full conventions](conventions/openadr-alliance-conventions.yml) · [Error catalog](errors/openadr-alliance-problem-types.yml) · [Data model](data-model/openadr-alliance-data-model.yml) · [Vocabulary](vocabulary/openadr-alliance-vocabulary.yml)

## Events

- Every VTN must support the **WEBHOOK** notifier binding; **MQTT** was added in 3.1.0 and is optional.
- Subscribe with `createSubscription`, naming object types, operations and a `callbackUrl` per entry, plus an optional subscriber-supplied `bearerToken`.
- For MQTT, discover bindings with `GET /notifiers`, then topic names with the twelve `GET /notifiers/mqtt/topics/*` operations. Topic names are VTN-assigned and may be VEN-scoped for object privacy — never hardcode them.
- [Webhook catalog](asyncapi/openadr-alliance-webhooks.yml)

## Docs

- [Specification overview](https://www.openadr.org/specification)
- [OpenADR 3 introduction and certification programme](https://www.openadr.org/openadr-3-0)
- [Specification download (registration form)](https://www.openadr.org/specification-download)
- [How to build a certified product](https://www.openadr.org/how-to-build-a-product)
- [OpenADR 3 certification](https://www.openadr.org/openadr-3-certification)
- [Cyber security and PKI](https://www.openadr.org/cyber-security)
- [Get implementation help](https://www.openadr.org/get-implementation-help)
- [FAQ](https://www.openadr.org/faq)

## Testing and certification

- Online test tool: https://test-tool.openadr.org/ (Alliance members; all certifications run here).
- Downloadable test assets for CI/CD on purchase of a test-tool licence.
- Free OpenADR test PKI certificates from Eonti (https://eonti.com/openadr); production certificates valid 20 years.
- Certification is profile-based for VENs (at least one profile) and all-features for VTNs; final verification at an Alliance-appointed test house.
- [Sandbox / test surface](sandbox/openadr-alliance-sandbox.yml)

## Packages (all third-party — the Alliance ships none)

- `openleadr` (PyPI, OpenLEADR/LF Energy) — OpenADR 2.0b VEN/VTN library.
- `openadr3-client` (PyPI, ElaadNL) — OpenADR 3 client.
- `openadr3` (PyPI, Clark Communications) — OpenADR 3 entity API library.
- `@celabs/openadr-ven`, `node-red-contrib-openadr`, `@anl-ioc/node-red-contrib-oadr-ven` (npm) — OpenADR 2.0 VENs.
- [Full package inventory](packages/openadr-alliance-packages.yml)

## Standards lineage

- OpenADR 2.0b was approved by the IEC as Publicly Available Specification **IEC/PAS 62746-10-1**.
- The 2.0 lineage builds on OASIS Energy Interoperation, EMIX and WS-Calendar; developed alongside the NIST Smart Grid standards effort.
- The Alliance also runs **EcoPort**, the certification programme for **CTA-2045-B**; OpenADR 3.1.1 carries `CTA2045_REBOOT` and `CTA2045_SET_OVERRIDE_STATUS` pass-through payloads.
- [Conformance assessment](conformance/openadr-alliance-conformance.yml)

## Directories

- [OpenADR certified products](https://products.openadr.org/)
- [EcoPort certified products](https://ecoport.openadr.org/)

## Other

- [Blog](https://www.openadr.org/openadr-alliance-blog)
- [Press releases](https://www.openadr.org/press-releases)
- [Contact](https://www.openadr.org/contact-us)
- [Public Apache-2.0 mirror of the OpenADR 3 specification](https://github.com/grid-coordination/openadr3-specification)