3 Accessing the GraphQL APIs Using Utility-Scoped Tokens

The Oracle Utilities GraphQL APIs require proper authentication through access tokens and base URL construction to gain access and use of the APIs. A user can obtain a utility-scoped access token that allows retrieving user data from the GraphQL APIs for all accounts within a utility.

Retrieving Utility-Scoped Access Tokens

The GraphQL APIs support the OAuth 2.0 standard for authentication. OAuth 2.0 is an authorization framework that enables an application or a service to obtain limited access to a protected HTTP resource. In OAuth, the applications are called clients, and clients access protected resources by presenting an access token to the HTTP resource.

OAuth 2.0 is typically used in the "three-legged" fashion, in which an end-user authorizes a third-party to access their data. However, the Oracle Utilities GraphQL API uses "two-legged" authorization, which allows a trusted developer (for example, a utility company) to access all data Oracle Utilities provides.

Obtaining Credentials

Provide the following information, using https://support.oracle.com, to your Oracle Utilities Customer Success Representative:

  • Contact name
  • Contact email
  • The specific utility code to access if multiple operating companies exist

Oracle Utilities provides you with the following keys:

  • client_id
  • client_secret
  • grant_type

For example, a client's contact information is sent through https://support.oracle.com to Oracle Utilities:

  • Name: Integration Team
  • Email: IntegrationTeam@utilityX.com
  • Utility Access: UtilityX

The client receives Oracle Utilities information through a secure email:

  • client_id: 019ebf3c-bc9c-41fa-87aa-09b1ecc86012
  • client_secret: bdf46a70-c553-44bd-846e-7bd4f9d98690
  • grant_type: client_credentials

It is recommend that you retain all information provided to obtain credentials as it is required in the case of a forgotten client_id.

Securing your Credentials and Requesting New Credentials

Keys can be used to access utility customer data, so they must be protected and stored securely. Keys must have limited distribution, they should not be shared among developers, and they must only be used by authorized utility personnel. Do not use keys or tokens directly in a browser or mobile application. To make data from Oracle Utilities GraphQL APIs available to customers, you must create a server-side API gateway to accept customer requests for data using their session token. Your server-side API gateway must then make a request to the Oracle Utilities GraphQL APIs using your utility's OAuth token.

If you suspect that a key has been compromised or its security can no longer be assured, contact Oracle Utilities using https://support.oracle.com with the client_id. A new client_secret is issued.

If credentials are forgotten, you can request new credentials from Oracle Utilities. If the client_secret is forgotten, you must send a communication using https://support.oracle.com with your client_id. Oracle Utilities will issue a new client_secret. If the client_id is forgotten, you must send a communication using https://support.oracle.com with the information provided when first obtaining credentials, and Oracle Utilities issues a new client_id and client_secret.

Obtaining a Utility-Scoped Access Token

Before calling other API endpoints for a given tier, a client must obtain a utility-scoped access token from the authorization-v1 endpoint (authorization-v1/oauth2/token) using the issued client credentials.

To obtain a client access token:

  1. Use a curl command to request the utility-scoped access token. If you choose to use a different method for this type of request, be aware that the -u option below performs Base64 encoding on the client_id:client_secret value. The syntax of this command is as follows: 

    curl -XPOST host:port/apis/authorization-v1/oauth2/token -d "grant_type=client_credentials" -u "client_id:client_secret" -H "Content-Type: application/x-www-form-urlencoded"

    You must replace host, port, client_id, and client_secret with the applicable values.

    An example response is provided below:

    {
  "client_id":"019ebf3c-bc9c-41fa-87aa-09b1ece86012",
   "access_token":"a3b96ccb-cff0-4c12-b693-40e7158aa8cd",
   "token_type":"BEARER",
   "scope":"",
   "expires_in":3599
}

    The expires_in parameter is expressed in seconds.

  2. After retrieving the utility-scoped access token, you can provide the utility-scoped access token as part of your GraphQL queries, which is described in Using the GraphiQL IDE and Using Curl. If the utility-scoped access token expires, repeat the process to obtain a valid access token.

Constructing the Base URL

A GraphiQL Integrated Development Environment (IDE) provides access for you to explore the schema and run queries using utility-scoped access tokens. You can access the IDE using the following URL structure:

  • Stage Environment: https://api-stage.us.opower.com/graphql

    This environment is intended for API call and feature testing.

  • Production Environment: https://api.us.opower.com/graphql

    This environment is intended to be used for updates or retrievals from your production system that directly supports your customers.