Skip to content

User Guide:

Public API Registration and Authentication


Registration

To access ERCOT APIs, you must register as a user on the ERCOT API Explorer website.

    1. Navigate to API Explorer in a web browser.
      API Explorer

    2. Click the Sign In/Sign Up button in the top-right corner to open the Sign in form in a new window.
      sign in screen

    3. Click the Sign up now link at the bottom of the form to begin registering your new account.

    4. Enter your email address in the form and click the Send verification code button.

    5. Retrieve the verification code from your email and enter the code in the Verification Code field. Click the Verify code button to complete your email verification.

    6. Once your email address has been verified, you will be able to enter a password of your choosing, your display name, and your first and last name into the form. Click the Create button to complete the registration of your account.

    7. When your account registration is complete, you will be signed into the API Explorer website and have the option to sign out by clicking the Sign Out link in the top-right corner.


Authentication and authorization

Once you have registered, you can then access the ERCOT Public API. There are three components to this process:

Extract the subscription key from the API Explorer

    1. Sign in to the API Explorer in a web browser.
      sign in screen

    2. Navigate to the Products page found in the top navigation.

    3. Select the product that you wish to subscribe to from the table: Public API.

    4. Enter a name for your subscription: ie. Public API.

    5. Click the Subscribe button and you will be redirected to your Profile page to view your active subscriptions.

    6. Click the Show button and copy the value of the Primary key.

    NOTE: It is only necessary to extract a subscription key once.


Obtain an ID token

ID tokens are valid for one hour. There is no way to refresh an ID token. A new ID token may be acquired by sending another POST request.

Required Query Parameters:

Key Value
URL https://ercotb2c.b2clogin.com/ercotb2c.onmicrosoft.com/B2C_1_PUBAPI-ROPC-FLOW/oauth2/v2.0/token
grant_type password
username <username>
password <password>
scope openid+fec253ea-0d06-4272-a5e6-b478baeecd70+offline_access
client_id fec253ea-0d06-4272-a5e6-b478baeecd70
response_type id_token

Below are examples for obtaining an ID token with either Postman , cURL, or JavaScript.

Create a POST request in Postman

  1. Create a POST request in Postman with the query parameters listed above:
  2. Click the Send button.
  3. Validate that a HTTP 200 OK response status was received and inspect the response JSON payload for the id_token value.

response:

Create a request in cURL

  1. Send a POST request to retrieve an ID token.
  2. Inspect the response payload for the id_token field.
curl --data '' --request POST 'https://ercotb2c.b2clogin.com/ercotb2c.onmicrosoft.com/B2C_1_PUBAPI-ROPC-FLOW/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'username=user@email.com' \
--data '&password=****' \
--data '&grant_type=password' \
--data '&scope=openid+fec253ea-0d06-4272-a5e6-b478baeecd70+offline_access' \
--data '&client_id=fec253ea-0d06-4272-a5e6-b478baeecd70' \
--data '&response_type=id_token'

response:

Create a request in JavaScript

  1. Send a POST HTTP request to retrieve an ID token.
  2. Inspect the response JSON payload for the id_token field.
const USERNAME = "username";
const PASSWORD = "password";

const RESOURCE = "https://ercotb2c.b2clogin.com/ercotb2c.onmicrosoft.com/B2C_1_PUBAPI-ROPC-FLOW/oauth2/v2.0/token"
    + "?username=" + USERNAME
    + "&password=" + PASSWORD
    + "&grant_type=password"
    + "&scope=openid+fec253ea-0d06-4272-a5e6-b478baeecd70+offline_access"
    + "&client_id=fec253ea-0d06-4272-a5e6-b478baeecd70"
    + "&response_type=id_token";

const OPTIONS = {
    method: 'POST'
};

fetch(RESOURCE, OPTIONS)
.then(response => response.json())
.then(result => console.log(result.id_token))
.catch(error => console.log('error', error));

response:


Access the API using the ID token and subscription key

Note

Developers must provide a valid subscription key and ID token in HTTP requests to the API. Without these credentials, the calls will be rejected.

Below are examples for accessing the API using the ID token and subscription key with either Postman , cURL, or JavaScript.

Create a GET request in Postman

  1. On the Authorization tab, set the Type as “Bearer Token”. In the Token field, enter the id_token obtained previously.
  2. On the Headers tab, provide the subscription key: Ocp-Apim-Subscription-Key.
  3. Validate that a HTTP 200 OK response status was received and inspect the response JSON payload.

response:

Create a request in cURL

  1. Add the Subscription Key and ID Token to cURL command.
curl --location --request GET 'https://api.ercot.com/api/public-reports' \
--header 'Ocp-Apim-Subscription-Key: 4ce1f2...' \
--header 'Authorization: Bearer eyJhbGc...'

response:

Create a request in JavaScript

  1. Add the Subscription Key to the header of your API requests using the “Ocp-Apim-Subscription-Key” header.
  2. Add the ID Token to the "authorization" header of your API requests. Make sure to prefix the token with the authentication scheme "Bearer".
const SUBSCRIPTION_KEY = "your_subscription_key";
const ID_TOKEN = "acquired_id_token";
fetch("https://api.ercot.com/api/public-report/", {
    "headers": {
        "authorization": "Bearer " + ID_TOKEN,
        "Ocp-Apim-Subscription-Key”: SUBSCRIPTION_KEY,
    },
    "method": "GET",
}).then(response => response.json())
.then(data => console.log(data));

response: