# Green Button Alliance

> The Green Button Alliance (GBA) is the non-profit that stewards, tests and certifies
> the Green Button standard - the NAESB REQ.21 Energy Services Provider Interface (ESPI)
> profile for utility customer electricity, natural gas and water usage data, in its
> Download My Data (DMD) and Connect My Data (CMD) forms. GBA publishes interface
> contracts and certifies other organisations against them; it operates no production
> consumer-data or market-data API of its own. Its ESPI sandbox is out of service with a
> replacement expected 2026Q3, and the normative NAESB standard must be purchased.
> Green Button is voluntary in the United States - obligation arrives only through state
> action and, outside the US, Ontario's O. Reg. 633/21.

Generated by API Evangelist on 2026-07-27. GBA publishes no llms.txt of its own
(https://www.greenbuttonalliance.org/llms.txt returned 404). Every link below was
verified reachable on that date unless marked otherwise.

## Read this first

- Green Button is a **contract, not an endpoint**. The base URL you call belongs to a
  certified Data Custodian (a utility or its platform provider), never to
  greenbuttonalliance.org.
- OAuth scopes are **ESPI Function Block strings**, e.g.
  `FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13` - not words
  like `read:usage`.
- Responses on the resource server are **Atom/XML** (`application/atom+xml`), not JSON.
- GBA's own OIDC discovery document is **member single sign-on for the association**. It
  grants no access to any energy data.

## Specifications

- [Green Button CMD ESPI Resource Server OpenAPI](https://github.com/GreenButtonAlliance/OpenAPI-Green-Button-Documentation): OpenAPI 3.0.0, Apache-2.0. 7 read operations under /espi/1_1/resource - ApplicationInformation, Authorization, UsagePoint, Batch/Bulk.
- [OpenESPI Authorization Server OpenAPI](https://github.com/GreenButtonAlliance/OpenESPI-GreenButton-Java/blob/main/openespi-authserver/docs/openapi.yaml): OpenAPI 3.0.3, Apache-2.0. 16 operations - OAuth2 client management, DataCustodian integration, OIDC UserInfo, OAuth2 protocol endpoints. TLS 1.3 only, X.509 mutual TLS supported. No operationIds declared.
- [ApplicationInformation OpenAPI](https://github.com/GreenButtonAlliance/SwaggerHub-GreenButton-API-Documentation): OpenAPI 3.0.3, Apache-2.0. The RFC 7591/7592 registration record with real per-field examples.
- [NAESB REQ.21 ESPI standard](https://www.naesb.org/espi_standards.asp): the normative document. **Paywalled** - purchase v4.0 or v3.3 from NAESB or receive it as a NAESB member benefit.
- [Legacy Swagger 1.2 resource listings](https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/api-docs): superseded, but covers 11 ESPI resources versus the 7 paths in the current OpenAPI.

## Docs

- [Developer Resources](https://www.greenbuttonalliance.org/developer-resources): the developer portal - curated RFC/NAESB/GitHub links plus technical notes.
- [API Reference (Swagger UI)](https://greenbuttonalliance.github.io/OpenESPI-GreenButton-API-Documentation/API/)
- [Technical Information](https://www.greenbuttonalliance.org/technical-info)
- [Function Blocks](https://www.greenbuttonalliance.org/function-blocks): the ESPI function-block catalog - simultaneously the certification test grouping and the OAuth scope vocabulary.
- [Connect My Data Function Blocks](https://www.greenbuttonalliance.org/cmd-function-blocks)
- [Access Tokens](https://www.greenbuttonalliance.org/access-tokens): the six ESPI token types.
- [OAuth 2.0 Access and Refresh Token Duration](https://www.greenbuttonalliance.org/oauth-20-access-and-refresh-token-duration)
- [Generating Persistent UUIDs](https://www.greenbuttonalliance.org/generating-persistent-uuids)
- [Atom Elements](https://www.greenbuttonalliance.org/atom-elements) and [Atom & ESPI](https://www.greenbuttonalliance.org/atom-and-espi)
- [Power-of-Ten Multiplier](https://www.greenbuttonalliance.org/poweroftenmultiplier), [Cost and Currency](https://www.greenbuttonalliance.org/costandcurrency), [Daylight-Savings Time](https://www.greenbuttonalliance.org/daylight-savings-time)
- [Technical FAQs](https://www.greenbuttonalliance.org/faqs-technical)

## Certification and directory

- [Certification Testing](https://www.greenbuttonalliance.org/testing)
- [Purchase Certification](https://www.greenbuttonalliance.org/offerings/certification): Data Custodian DMD $3,000, CMD $3,200, combined $3,700. Membership not required.
- [Certification Preparation](https://www.greenbuttonalliance.org/certification-preparation-dc)
- [Green Button Directory Services](https://www.greenbuttonalliance.org/directory-services): free public listings of utilities, third-party apps and platform providers. HTML only - no API, and the terms forbid automated retrieval.
- [DMD Validator](https://dmdvalidator.greenbuttonalliance.org/): browser-based Download My Data file validator.

## Sandbox

- [Sandbox status](https://www.greenbuttonalliance.org/sandbox): **unavailable**. GBA states the replacement platform "won't be ready until sometime in 2026Q3". The declared sandbox hosts return 403 to anonymous probes.
- [OpenESPI reference implementation](https://github.com/GreenButtonAlliance/OpenESPI-GreenButton-Java): Apache-2.0 Java monorepo (common, datacustodian, thirdparty, authserver, handoff) - the realistic way to test today.
- [Published wire-contract fixtures](https://github.com/GreenButtonAlliance/OpenESPI-GreenButton-Java/tree/main/contracts): canonical token-response, back-channel and BatchList notification payloads.

## API Evangelist artifacts

- openapi/green-button-alliance-green-button-api-openapi.yml
- openapi/green-button-alliance-authorization-server-openapi.yml
- openapi/green-button-alliance-application-information-openapi.yml
- authentication/green-button-alliance-authentication.yml
- scopes/green-button-alliance-scopes.yml
- vocabulary/green-button-alliance-function-blocks.yml
- conventions/green-button-alliance-conventions.yml
- errors/green-button-alliance-problem-types.yml
- lifecycle/green-button-alliance-lifecycle.yml
- conformance/green-button-alliance-conformance.yml
- data-model/green-button-alliance-data-model.yml
- asyncapi/green-button-alliance-webhooks.yml
- sandbox/green-button-alliance-sandbox.yml
- rate-limits/green-button-alliance-rate-limits.yml
- packages/green-button-alliance-packages.yml
- well-known/green-button-alliance-well-known.yml
- security/green-button-alliance-domain-security.yml
- security/green-button-alliance-vulnerability-disclosure.yml
- mcp/green-button-alliance-mcp.yml
- mcp/green-button-alliance-tool-crosswalk.yml
- agentic-access/green-button-alliance-agentic-access.yml
- skills/_index.yml
- examples/_index.yml

## What does not exist

- No MCP server, no GraphQL surface, no gRPC/protobuf.
- No AsyncAPI document, though a CMD-mandatory push model (FB_39, FB_69) genuinely exists.
- No published client library on npm, PyPI or Maven Central - source only, on GitHub.
- No CLI, no embedded UI components, no dated changelog, no status page, no SLA.
- No /.well-known/security.txt (the disclosure policy lives in the repository SECURITY.md, security@greenbuttonalliance.org).
- No machine-readable registry of certified implementations.

## Security

- [Security policy](https://github.com/GreenButtonAlliance/OpenESPI-GreenButton-Java/blob/main/openespi-common/SECURITY.md): report to security@greenbuttonalliance.org, acknowledgment within 48 hours, initial assessment within one week. No public issues for vulnerabilities.
- [Legal / Terms & Conditions](https://www.greenbuttonalliance.org/legal)
- [Privacy Policy](https://www.greenbuttonalliance.org/privacy-policy)

## Organisation

- [About](https://www.greenbuttonalliance.org/about-us) - North Carolina 501(c)(3), PO Box 268, Jamison, Pennsylvania 18929.
- [Membership](https://www.greenbuttonalliance.org/membership-information) | [Member Directory](https://www.greenbuttonalliance.org/member-directory/) | [Join](https://www.greenbuttonalliance.org/register) | [Login](https://www.greenbuttonalliance.org/login)
- [News](https://www.greenbuttonalliance.org/news) | [Events](https://www.greenbuttonalliance.org/events/) | [Contact](https://www.greenbuttonalliance.org/contact-us)
- [GitHub](https://github.com/GreenButtonAlliance) | [LinkedIn](https://www.linkedin.com/company/green-button-alliance)
- [U.S. Initiatives](https://www.greenbuttonalliance.org/us-initiatives) | [Canadian Initiatives](https://www.greenbuttonalliance.org/canadian-initiatives) | [European Initiatives](https://www.greenbuttonalliance.org/eu-initiatives) | [Korean Initiatives](https://www.greenbuttonalliance.org/korean-initiatives)