Welcome to the OAuth server

This server implements OAuth 2.0:

Getting started

To use this OAuth server, please contact us to request an OAuth application.

Please provide a short description of the application you are creating, along with the details below. No worries if you are unsure - we can use the description you provide to help.

  1. The client type: public or confidential?
  2. The grant type: authorization, client-credentials or device?
  3. The allowed redirect URIs.
  4. The resources you would like to access. Please explore our API documentation, and our GraphQL API.

Example (authorization)

1. Generate PKCE code verifier and challenge

// Generate a code verifier (random string)
const codeVerifier = crypto.randomUUID().replace(/-/g, '');

// Create a code challenge (SHA-256 hash of verifier)
const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const digest = await crypto.subtle.digest('SHA-256', data);
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

2. Request authorization

GET /authorize/?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

3. Exchange authorization code for access token

POST /token/
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&code_verifier=YOUR_CODE_VERIFIER

4. Access protected resource

GET /resource/
Authorization: YOUR_ACCESS_TOKEN

Example (client credentials)

1. Exchange credentials for an access token

POST /token/
Authorization: Basic BASE64_ENCODED(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

2. Access protected resource

GET /resource/
Authorization: YOUR_ACCESS_TOKEN

Example (device)

1. Authorize device

POST /device-authorization/
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID

The device should use the response to display or communicate the user_code and the verification_uri to the end user. Devices with screens can display this information visually, while devices without screens may use alternatives like audio or Bluetooth.

         +-----------------------------------------------+
         |                                               |
         |  Using a browser on another device, visit:    |
         |  https://auth.example.com/device              |
         |                                               |
         |  And enter the code:                          |
         |  ETE39050                                     |
         |                                               |
         +-----------------------------------------------+

The user visits the verification_uri to authenticate, inputs the user_code and authorizes the device.

2. Exchange device code for access token

While the user is authorising, the device should periodically attempt to acquire an access token (at a rate specified by the interval seconds):

POST /token/
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&device_code=DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code

3. Access protected resource

GET /resource/
Authorization: YOUR_ACCESS_TOKEN

Example (token exchange)

RFC 8693 delegation semantics are supported. This means that you will use the client credentials token in both the Authorization header and the actor_token, as shown below.

1. Retrieve an access token for your client credentials app, as described in Example (client credentials).

2. Assuming EXTERNAL_IDP_USER_ACCESS_TOKEN has been issued by your external IdP, perform the token exchange call:

POST /token
Authorization: YOUR_CLIENT_CREDENTIALS_ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded

grant_type="urn:ietf:params:oauth:grant-type:token-exchange"&
actor_token_type="urn:ietf:params:oauth:token-type:access_token"&
actor_token=YOUR_CLIENT_CREDENTIALS_ACCESS_TOKEN&
subject_token_type="urn:ietf:params:oauth:token-type:access_token"&
subject_token=EXTERNAL_IDP_USER_ACCESS_TOKEN

3. Access protected resource

GET /resource/
Authorization: YOUR_ACCESS_TOKEN

Resources

Octopus Energy API