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 form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

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.
  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'
      operationId: getUserinfo
      x-operation-id-source: derived
    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'
      operationId: postUserinfo
      x-operation-id-source: derived
components:
  schemas:
    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
    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
  responses:
    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'
    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'
    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'
  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