1. Documentation
  2. Green Button
  3. Authorization Scope

Green Button Authorization Scope

When requesting utility data from a customer, you have the option to request specific types of utility data and the period for which you will continue to have access to the customer's data. For example, you can specify a scope to only request historical interval data. Alternatively, you can also specify a scope that requests ongoing access to new bill and interval data for up to 3 years. These options are all defined in the scope string parameter.

NOTE: The parameters you set in the scope string of an authorization url simply prefill the OAuth form. The user does have the ability to edit the scope parameters (e.g. shorten the authorization duration, etc.), and we may add additional scope parameters and function blocks to let you know what the final scope of functionality is. So be sure to check the final scope string you get with the access token (e.g. OAuth Step 4).

The scope string in Green Button Connect made up of a list of parameters (the FB parameter is always required), separated by semicolons (;): 

FB=<FUNCTION_BLOCK_LIST>;<OPTION_NAME>=<OPTION_VALUE>;<OPTION_NAME>=<OPTION_VALUE>...

For example, here's a valid scope string for an authorization url: 

FB=4_16_51;HistoryLength=34128000

Here's the scope parameters that can be used in authorization urls:

Parameter Format Default Description Example
FB List (Function Block) [N/A, required] [required] The list of data and functionality you are requesting in the authorization. Separate with underscores (_). See Function Blocks for a list of valid function block combinations. FB=4_16_51
HistoryLength Integer 63072000 (2 years) How far back you want historical data. If you don't want historical data, set this to 0. HistoryLength=63072000
PreferredAuthEndDate Integer Three years from current time A unix timestamp for when you want to automatically revoke the authorization. If you don't want to set an automatic end date (e.g. continue until the user revokes), set this to 0. PreferredAuthEndDate=1403190000
AdditionalScope List (Additional Scope) "" (empty string) A list of additional universal and utility-specific scope options. Separate with underscores (_). See Additional Scope for a list of possible values. AdditionalScope=noedit_meters-all

You may see some other scope parameters in the final scope string that you aren't able to include in the original authorization url (mostly because they are just informative about certain functionality and not something you are requesting during authorization). Below is a list of these parameters and what they mean:

  • AccountCollection - integer - How many UsagePoints are available under the authorization.
  • BR - integer - The Bulk ID for the Bulk API.
  • IntervalDuration - integer - How long interval data points are (in seconds) (e.g. 900 means 15min intervals).
  • BlockDuration - integer or Named Frequency - How long chunks of interval data are (in seconds) (e.g. 86400 means 1 day per chunk).

Here's an example final scope string that includes some of these other parameters: 

FB=1_3_4_5_8_13_14_18_19_34_35_39_51;IntervalDuration=900_3600;BlockDuration=daily;HistoryLength=34128000;SubscriptionFrequency=daily;AccountCollection=2

Function Blocks are the various types of data and functionality you can request during an authorization. To build a function block list in the scope string, concatenate each function block (sorted lowest to highest) into a list separated by underscores (_).

NOTE: For the FB list in an authorization url, we only look for a subset of function blocks (4, 16, and 51), so you only have to worry about that subset of options when building your authorization urls (see examples below). However, when you get the full scope string back with your access_token, we will include all the other function blocks that are relevant to your authorization (see the full reference table).

Here's the function blocks that can be used in authorization urls (we ignore other valid function blocks):

FB Name Description
4 Interval Metering Ask for permission to access a customer's anonymous interval data.
16 Usage Summary with Costs Ask for permission to access a customer's bill data.
51 Core Retail Customer Ask for permission to access a customer's account details (account number, service address, etc.).

Here's some example function block lists for authorization urls: 

# Everything - Intervals, Usage Summary with Costs (e.g. bills), and Retail Customer (e.g. account details)
FB=4_16_51

# Anonymous intervals only
FB=4

# Intervals and account details (no bills)
FB=4_51

While we only support a specific subset of function blocks in authorization url scope strings, there are many other function blocks that describe various Green Button functionality. During or after an authorization, we try to update the final function block list to include all the data specifics and functionality for that authorization (so you know what to expect).

For reference, here's a table of what each number in the function block list means (use this table if you're parsing the function blocks from the final scope string function block list):

Function Block Name
1 Common
2 Download My Data
3 Connect My Data
4 Interval Metering
5 Interval Electricity Metering
6 Demand Electricity Metering
7 Net Metering
8 Forward and Reverse Metering
9 Register Values
10 Gas
11 Water
12 Cost of Interval Data
13 Security and Privacy Classes
14 Authorization and Authentication (replaced by FB 31)
15 Usage Summary
16 Usage Summary with Cost
17 Power Quality Summary
18 Multiple Usage Points
19 Partial Update Data
27 Usage Summary with Demands and Previous Day Attributes
28 Usage Summary Costs for Current Billing Period
29 Temperature Interval Metering
30 Common User Experience (DMD only)
31 Authorization and Authentication w/o Pre-Negotiated Scope
32 Resource Level REST
33 Management REST Services
34 SFTP for Bulk
35 REST for Bulk
36 Third Party Dynamic Registration
37 Query Parameters
38 On Demand Requests
39 PUSH Model
40 Offline Authorization
41 Manage ApplicationInformation Resource
44 Manage Authorization Resource
46 Core Retail Customer (recently replaced by FB 51, but still works in scope string for backwards compatibility)
47 REST for Retail Customer Bulk (replaced by FB 67)
48 SFTP for Retail Customer Bulk (replaced by FB 66)
49 Retail Customer Management REST
50 Retail Customer Resource Level REST
51 Retail Customer Common
52 Retail Customer Download My Data
53 Retail Customer Connect My Data
54 Retail Customer Basic Information
55 Retail Customer Demographic Information
56 Retail Customer Billing Information
57 Retail Customer AccountAgreement Information
58 Retail Customer ServiceLocation Information
59 Retail Customer ServiceSupplier Information
60 Retail Customer Meter Information
61 Retail Customer EndDevice Information
62 Retail Customer ProgramDateIdMappings Information
64 Retail Customer Security and Privacy
65 Retail Customer Authorization and Authentication w/o Pre-Negotiated Scope
66 SFTP for Retail Customer Bulk
67 REST for Retail Customer Bulk
68 Retail Customer Query Parameters
69 Retail Customer PUSH Model
70 Retail Customer Offline Authorization

Here are some time frequencies you may see in scope strings.

Named Frequency Description
billingPeriod Update on or shortly after the billing period.
daily Update once per day (time of day varies based on server load).
monthly Update on or shortly after the start of each month.
seasonal Update on or shortly after the start of each utility season.
weekly Update on or shortly after the start of each week.
yearly Update on or shortly after the start of each year.
quarterly Update on or shortly after the start of each quarter.

Here are the possible additional scopes you can use in the AdditionalScope parameter:

Additional Scope Default Description Examples
sou-{scope-of-use} sou-default This scope lets us know which predefined Scope of Use you would like to disclose to the user during authorization. If not included, your default scope of use is used. sou-energyaudit
meters-(all|{SAID}) None selected (e.g. user has to pick)

During authorization, the user is asked which utility services (e.g. meters) they would like the authorize for data sharing. You can pre-select all the services (meters-all) or, if you know the service account identifier (SAID) for a specific service, you can specify it to be pre-selected (e.g. meters-1234567890).

meters-all meters-1234567890 meters-123456789-0
auth-{type}[-{value}] Default authentication flow

If not already authenticated, we will ask the user to prove they are who they say they are (called "authentication"). However, since utility customers often don't have an online account or remember their password, we try to offer multiple ways of authenticating (usually by sending them a one-time-passcode (OTP) and asking them to type it in).

In order to streamline the authentication process, you can signal to us a preferred authentication flow to use and optionally specify some user identifier value to pre-fill. That way, in ideal scenarios, all the user has to do is click to receive an OTP and then type that verification code in.

Here are the docs for utilities that support this parameter:

auth-login auth-phone-5554443333 auth-email-aaa@bbb.com auth-sso-{id} auth-utility-{utility_id}
noedit Scope is editable by user

Don't allow the customer to modify the scope during the OAuth process. This basically enables a take-it-or-leave-it authorization process. You typically want to use this when you have to have a specific set of data or a specific authorization duration.

noedit

As part of our DataGuard compliance for Green Button Connect implementations, we want to encourage transparency by offering the ability for you to provide some specific information to the user on what you intend to do with the data they are sharing (i.e. what is your "scope of use"). That way, the user can be more familiar and comfortable with what you are doing.

By default, the scope-of-use is completely open-ended, and during authorization, the user is told that you haven't disclosed how you'll use the data. If you'd like to change that to be more transparent on how you will used the shared data, you can specify additional scopes of use in your settings. If you have multiple products or business use cases, you can define multiple scopes of use, and then choose which one you want the user to see in the OAuth interface by including it to your scope string AdditionalScope parameters.

For example, if you are only going to use the shared data for an energy audit, you can add an energy audit scope-of-use in your settings:

  • Parameter: energyaudit
  • Description: "Your data will be used to compile the home energy audit you are requesting."
  • URL (optional): https://mysite.com/energy-audits/terms

Then, you can specify that scope-of-use in your AdditionalScope parameter:

  • FB=4_16_51...;AdditionalScope=sou-energyaudit...

The user will see the description and link for your energyaudit scope-of-use on the OAuth authorization page, and it will be logged in their authorization receipt that we send them when they authorize.

UtilityAPI - Oakland, California - info@utilityapi.com