Using OAuth 2.0 Authentication

The Oracle Utilities Opower REST 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 Opower REST 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 Opower 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 Opower 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 Client Access Token

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

Note:

In addition to the steps below, see Managing REST API Requests and Responses Using Postman for steps to obtain an access token using Postman.

To obtain a client access token:

  1. Use a curl command to request the 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, in which you must replace hosthost, port, client_id, and client_secret with the applicable values. 
    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"
    An example response is provided below: 
    {
	"client_id":"019ebf3c-bc9c-41fa-87aa-09b1ecc86012",
	"access_token": "a3b96ccb-cff0-4c12-b693-40e7158aa8cd",
	"token_type": "BEARER",
	"expires_in": 3599 
}

    Note:

    The expires_in parameter is expressed in seconds.
  2. If the access token expires, repeat the process to obtain a valid access token.

Calling APIs Using the Access Token

After obtaining an access token, a client can call any of the associated API endpoints. The access token must be included in the HTTP header for authorization.

HTTP Header Components:

  • Key: Authorization
  • Value: Bearer access_token
  • Type: String
  • Optional: No