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.

The client type: public or confidential?
The grant type: authorization, client-credentials or device?
The allowed redirect URIs.
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 authorization server then responds with a JSON payload similar to this one

{
    "device_code": "EATdQqZXYqoif17b7sIFKK82vdlCFI",
    "verification_uri": ""https://auth.oe-kraken.systems/device"",
    "user_code": "ETE39050",
    "expires_in": 1800,
    "interval": 5
}

Now, the device needs 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.oe-kraken.systems/device        |
         |                                               |
         |  And enter the code:                          |
         |  ETE39050                                     |
         |                                               |
         +-----------------------------------------------+

The user visits the verification_uri (where they need to be/get logged in), introduces the user_code and authorizes the device.

2. Authenticate device

After performing the /device-authorization request, the device should attempt to acquire an access token every few seconds (at a rate specified by interval in seconds) by performing the following request while the user is authorizing the device.

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

That request will return error messages until the user authorizes the device or the device session expires. The success response will look like this one where the access_token is returned:

{
    "access_token": YOUR_ACCESS_TOKEN,
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "openid full-customer-access",
    "refresh_token": YOUR_REFRESH_TOKEN
}

Octopus Energy