Authentication

Access to the API is controlled using temporary JSON Web Tokens (JWT).

Identification

Before using the API, Uswitch will provide you with the following:

Client identifier - Identifies you to the authentication service
Client secret - Proves your claimed identity is true.

These are used to obtain access tokens.

Staging and production use the same credentials. Switch API and Reporting API also use the same set of credentials.

1. Fetch an access token

Request an access token as per the example below.

Authentication URL: https://auth.energy.uswitchsuppliers.com/oauth/token

Depending on the environment, set the audience as follows:

Staging: https://staging-api.energy.uswitchsuppliers.com/
Production: https://api.energy.uswitchsuppliers.com/

Using your Client ID and Client Secret in place of CLIENT_ID and CLIENT_SECRET below, make a request to obtain a fresh token.

curl --request POST \
     --url 'https://auth.energy.uswitchsuppliers.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{ "grant_type": "client_credentials",
               "audience":"https://staging-api.energy.uswitchsuppliers.com/",
               "client_id": CLIENT_ID,
               "client_secret": CLIENT_SECRET }'

This will return JSON containing the token and permitted brand keys.

{
  "access_token": "U29tZSBiYXNlIDY0IGVuY29kZWQgc3R1ZmY=...",
  "expires_in": 86400,
  "scope": "switch-api status-reporting supplier-name-key:test-supplier brand:test-supplier",
  "token_type": "Bearer"
}

2. Use the token to access the API

The access token retrieved in the previous step is added to all requests to the API in the headers. Specifically it goes in the Authorization header, as a Bearer token. In the URL, you should replace ENDPOINT with the specific name of the endpoint you are using.

curl https://api.energy.uswitchsuppliers.com/ENDPOINT \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eW91ciBrZXkgaGVyZQ==...'

Expired tokens

Tokens will need to be refreshed on a regular basis. The exact time may vary, but they will generally be valid for several hours. Expiry time indicator is returned when you generate an access token. The value is in seconds.

{
  ...
  "expires_in":86400,
  ...
}

Example response

In this case the authentication token is expiring in 24 hours, we are expecting you to generate a new token every day.

If you attempt to access the API with an expired token, it will return the 401 HTTP status code.

How is the token secured?

The token contains your identity and a request for access to the API. You can see the token contents by decoding it (for example, by using the site https://jwt.io). It is signed by the authorisation service using the RS256 cryptographic algorithm, and this will verified by our API to check it is valid and has not been altered. This ensures that the tokens cannot be faked, and no other parties can gain access to your customers’ information.

As the API uses HTTPS, the token will encrypted during transfer to the API.

What are my Client ID and Client Secret?

They are alpha-numeric keys that we will generate for you during onboarding. You will need to keep track of these in order to request access tokens. Since it controls access to your customers’ personal data, take care not to lose your Client Secret, or expose it publicly. It should not be checked into version control. If it is lost, we can invalidate it immediately.