OAuth 2.0 authorizations granted by retail customers to third-party applications.
openapi: 3.0.3
info:
title: Xcel Energy Green Button Connect My Data ApplicationInformation Authorization API
summary: OAuth 2.0 authorized customer energy usage data based on the NAESB ESPI standard.
description: 'Xcel Energy Green Button Connect My Data API based on the ESPI (Energy Services Provider Interface) standard developed by NAESB. Enables authorized third-party applications to access customer electricity and natural gas usage data captured by Xcel Energy smart meters. Resources are exposed as Atom feeds and entries containing UsagePoint, MeterReading, IntervalBlock, ReadingType, ElectricPowerUsageSummary, ElectricPowerQualitySummary, LocalTimeParameters, and customer information. Customer authorization is granted via OAuth 2.0 and follows the Green Button Connect specification used by utilities across North America.
'
version: 1.1.0
contact:
name: Xcel Energy Developer Portal
url: https://developer-apim.aws.xcelenergy.com/
license:
name: Proprietary
url: https://www.xcelenergy.com/privacy_policy
x-generated-from: documentation
x-last-validated: '2026-05-03'
x-standards:
- NAESB ESPI 1.1
- Green Button Connect My Data
servers:
- url: https://api.xcelenergy.com/DataCustodian/espi/1_1/resource
description: Xcel Energy Data Custodian (Production)
- url: https://developer-apim.aws.xcelenergy.com/DataCustodian/espi/1_1/resource
description: Xcel Energy Developer Sandbox
tags:
- name: Authorization
description: OAuth 2.0 authorizations granted by retail customers to third-party applications.
paths:
/Authorization:
get:
operationId: listAuthorizations
summary: List customer authorizations granted to the application
description: 'Returns an Atom feed of Authorization entries granted by retail customers to the calling third-party application.
'
tags:
- Authorization
security:
- clientAccessToken: []
parameters:
- $ref: '#/components/parameters/PublishedMin'
- $ref: '#/components/parameters/PublishedMax'
- $ref: '#/components/parameters/UpdatedMin'
- $ref: '#/components/parameters/UpdatedMax'
- $ref: '#/components/parameters/MaxResults'
- $ref: '#/components/parameters/StartIndex'
responses:
'200':
description: Atom feed of Authorization entries.
content:
application/atom+xml:
schema:
$ref: '#/components/schemas/AuthorizationFeed'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Authorization/{authorizationId}:
get:
operationId: getAuthorization
summary: Retrieve a single customer authorization
description: Returns the Authorization entry identified by authorizationId.
tags:
- Authorization
security:
- clientAccessToken: []
parameters:
- $ref: '#/components/parameters/AuthorizationId'
responses:
'200':
description: Atom entry containing the Authorization resource.
content:
application/atom+xml:
schema:
$ref: '#/components/schemas/Authorization'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
parameters:
UpdatedMax:
name: updated-max
in: query
required: false
description: Upper bound (inclusive) for the Atom entry updated timestamp.
schema:
type: string
example: '2026-04-30T23:59:59Z'
AuthorizationId:
name: authorizationId
in: path
required: true
description: Identifier of an Authorization granted by a retail customer.
schema:
type: string
example: auth-1234
MaxResults:
name: max-results
in: query
required: false
description: Maximum number of entries to return in the feed.
schema:
type: integer
minimum: 1
maximum: 1000
example: 100
PublishedMin:
name: published-min
in: query
required: false
description: Lower bound (inclusive) for the Atom entry published timestamp, in epoch seconds or ISO 8601.
schema:
type: string
example: '2026-01-01T00:00:00Z'
PublishedMax:
name: published-max
in: query
required: false
description: Upper bound (inclusive) for the Atom entry published timestamp, in epoch seconds or ISO 8601.
schema:
type: string
example: '2026-04-30T23:59:59Z'
UpdatedMin:
name: updated-min
in: query
required: false
description: Lower bound (inclusive) for the Atom entry updated timestamp.
schema:
type: string
example: '2026-01-01T00:00:00Z'
StartIndex:
name: start-index
in: query
required: false
description: 1-based index of the first entry to return for paginated feeds.
schema:
type: integer
minimum: 1
example: 1
responses:
Forbidden:
description: The token type does not grant access to the requested endpoint or resource.
Unauthorized:
description: Authentication failed or the access token is invalid or expired.
NotFound:
description: The requested resource was not found or is not authorized for this token.
schemas:
AtomEntry:
type: object
description: Atom entry envelope used to wrap ESPI resource payloads.
properties:
id:
type: string
description: Stable URI for the entry.
title:
type: string
description: Human-readable title of the entry.
published:
type: string
format: date-time
description: Time the entry was first published.
updated:
type: string
format: date-time
description: Time the entry was last updated.
link:
type: array
description: Atom link relations (self, up, related).
items:
type: object
properties:
rel:
type: string
example: self
href:
type: string
example: UsagePoint/1
content:
type: object
description: ESPI XML payload content.
AtomFeed:
type: object
description: Atom feed envelope used to wrap collections of ESPI resource entries.
properties:
id:
type: string
title:
type: string
updated:
type: string
format: date-time
link:
type: array
items:
type: object
properties:
rel:
type: string
href:
type: string
entry:
type: array
items:
$ref: '#/components/schemas/AtomEntry'
Authorization:
allOf:
- $ref: '#/components/schemas/AtomEntry'
- type: object
description: OAuth 2.0 authorization granted by a retail customer to a third-party application.
properties:
accessToken:
type: string
description: OAuth 2.0 access token.
authorizationUri:
type: string
format: uri
apDuration:
type: integer
description: Authorization period duration in seconds.
apStart:
type: integer
description: Authorization period start time as epoch seconds.
code:
type: string
description: OAuth 2.0 authorization code.
error:
type: string
errorDescription:
type: string
errorUri:
type: string
format: uri
expiresAt:
type: integer
description: Expiration time of the authorization as epoch seconds.
grantType:
type: integer
description: 1=authorization_code, 2=client_credentials, 3=refresh_token.
ppDuration:
type: integer
description: Publication period duration in seconds.
ppStart:
type: integer
description: Publication period start time as epoch seconds.
refreshToken:
type: string
resourceURI:
type: string
format: uri
responseType:
type: integer
scope:
type: string
state:
type: string
status:
type: integer
description: 0=revoked, 1=active.
thirdParty:
type: string
tokenType:
type: integer
description: 0=bearer, 1=mac.
AuthorizationFeed:
allOf:
- $ref: '#/components/schemas/AtomFeed'
securitySchemes:
accessToken:
type: oauth2
description: Customer-scoped access token issued via the OAuth 2.0 authorization-code grant.
flows:
authorizationCode:
authorizationUrl: https://api.xcelenergy.com/DataCustodian/oauth/authorize
tokenUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
refreshUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
scopes:
FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=34128000: Standard ESPI scope string for 15-minute electric usage data with 13 months of history.
clientAccessToken:
type: oauth2
description: Application-scoped client access token used for management endpoints (Authorization list, Bulk, ServiceStatus).
flows:
clientCredentials:
tokenUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
scopes:
DataCustodian_Admin_Access: Administrative scope used for application-level operations.
registrationAccessToken:
type: http
scheme: bearer
bearerFormat: Registration Access Token
description: Token issued at application registration; used to read or update ApplicationInformation.