Green Button Alliance

Green Button Alliance OIDC API

OpenID Connect endpoints

Documentation GitHub OpenAPI

Operations 2

GET /userinfo Get user information

POST /userinfo Get user information (POST)

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/green-button-alliance-oidc-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: OpenESPI Authorization Server OIDC API
  description: "OAuth2/OIDC Authorization Server for Green Button Alliance ESPI 4.0 compliant applications.\n\nThis API provides:\n- OAuth2 client management\n- DataCustodian integration\n- OIDC UserInfo endpoint with ESPI claims\n- NAESB ESPI 4.0 compliance features\n\n## Security\n\n- **TLS 1.3 ONLY**: All communications must use TLS 1.3\n- **Certificate Authentication**: Support for X.509 client certificates\n- **Bearer Token**: Required for API access\n- **Perfect Forward Secrecy**: All cipher suites support PFS\n\n## ESPI Compliance\n\nThis server is certified for NAESB ESPI 4.0 compliance and supports:\n- Green Button Connect My Data (CMD)\n- Function Block 4.5.15+ \n- Certificate-based client authentication\n- ESPI-specific scope validation\n"
  version: 1.0.0
  contact:
    name: Green Button Alliance
    email: support@greenbuttonalliance.org
    url: https://www.greenbuttonalliance.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://www.greenbuttonalliance.org/terms
servers:
- url: https://authorization.greenbuttonalliance.org
  description: Production server
- url: https://staging-authorization.greenbuttonalliance.org
  description: Staging server
security:
- BearerAuth: []
- ClientCertificate: []
tags:
- name: OIDC
  description: OpenID Connect endpoints
paths:
  /userinfo:
    get:
      tags:
      - OIDC
      summary: Get user information
      description: 'OpenID Connect UserInfo endpoint with ESPI-specific claims.


        Returns user information based on the scopes granted to the access token.


        **Standard OIDC Claims:**

        - `openid` scope: sub

        - `profile` scope: name, given_name, family_name, etc.

        - `email` scope: email, email_verified


        **ESPI-specific Claims:**

        - FB scopes: customer_id, usage_point_details, data_rights

        - Green Button Alliance extensions

        '
      security:
      - BearerAuth:
        - openid
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfoResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - OIDC
      summary: Get user information (POST)
      description: Alternative POST method for UserInfo endpoint
      security:
      - BearerAuth:
        - openid
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  description: Access token (alternative to Authorization header)
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfoResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
components:
  schemas:
    UserInfoResponse:
      type: object
      properties:
        sub:
          type: string
          description: Subject identifier
        name:
          type: string
          description: Full name
        given_name:
          type: string
          description: Given name
        family_name:
          type: string
          description: Family name
        preferred_username:
          type: string
          description: Preferred username
        email:
          type: string
          format: email
          description: Email address
        email_verified:
          type: boolean
          description: Email verification status
        locale:
          type: string
          description: Locale preference
        zoneinfo:
          type: string
          description: Time zone
        updated_at:
          type: string
          format: date-time
          description: Last update time
        aud:
          type: string
          description: Audience (client ID)
        iss:
          type: string
          description: Issuer
        iat:
          type: string
          format: date-time
          description: Issued at time
        exp:
          type: string
          format: date-time
          description: Expiration time
        auth_time:
          type: string
          format: date-time
          description: Authentication time
        scope:
          type: string
          description: Granted scopes
        customer_id:
          type: string
          description: DataCustodian customer identifier
        customer_type:
          type: string
          enum:
          - RESIDENTIAL
          - COMMERCIAL
          - INDUSTRIAL
          description: Customer type
        account_number:
          type: string
          description: Utility account number
        service_territory:
          type: string
          description: Geographic service territory
        espi_scopes:
          type: array
          items:
            type: string
          description: ESPI-specific scopes granted
        datacustodian_grant_id:
          type: string
          description: DataCustodian grant identifier
        authorized_usage_points:
          type: array
          items:
            type: string
          description: Authorized usage point IDs
        usage_point_details:
          type: array
          items:
            $ref: '#/components/schemas/UsagePointInfo'
          description: Detailed usage point information
        gba_version:
          type: string
          description: Green Button Alliance version
        espi_version:
          type: string
          description: NAESB ESPI version
        data_rights:
          type: array
          items:
            type: string
            enum:
            - ENERGY_USAGE_DATA
            - 15_MINUTE_INTERVALS
            - HOURLY_INTERVALS
            - DAILY_USAGE_DATA
            - MONTHLY_BILLING_DATA
            - ADMIN_ACCESS
            - UPLOAD_ACCESS
          description: Granted data access rights
    UsagePointInfo:
      type: object
      properties:
        usage_point_id:
          type: string
        usage_point_uuid:
          type: string
          format: uuid
        service_category:
          type: string
          enum:
          - ELECTRICITY
          - GAS
          - WATER
          - TIME
        service_kind:
          type: string
          enum:
          - ENERGY
          - DEMAND
          - VOLTAGE
          - CURRENT
        meter_number:
          type: string
        service_address:
          type: string
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
        error_uri:
          type: string
          format: uri
        timestamp:
          type: string
          format: date-time
        path:
          type: string
        correlationId:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: invalid_token
            error_description: The access token is invalid or expired
            timestamp: '2024-01-16T15:30:00Z'
    InsufficientScope:
      description: Insufficient scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: insufficient_scope
            error_description: Token missing required openid scope
            timestamp: '2024-01-16T15:30:00Z'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: server_error
            error_description: Internal server error
            timestamp: '2024-01-16T15:30:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ClientCredentials:
      type: http
      scheme: basic
    ClientCertificate:
      type: mutualTLS
externalDocs:
  description: OpenESPI Authorization Server Documentation
  url: https://docs.greenbuttonalliance.org/authorization-server