The Authorization Code flow is the standard OAuth 2.0 flow for third-party applications that need to access the API on behalf of customers (RFC 6749 §4.1).

This flow is ideal when you need customer consent to access their data, such as when allowing a third-party Home Energy Management System (HEMS) to retrieve price information for a customer’s subscription. The flow ensures that the customer explicitly authenticates with Nomos and grants authorization to your application to access their data. Here’s how it works:

Keep your client_secret secure and never expose it in client-side code. Store it securely on your backend server and only use it there to exchange authorization codes and refresh tokens for access tokens.

1

Get your credentials

Contact support@nomos.energy to obtain your client_id and client_secret. You’ll also need to configure your authorized redirect URIs.

2

Redirect to authorization

Direct customers to our authorization endpoint where they will first authenticate with their Nomos credentials and then consent to your application accessing their data:

https://api.nomos.energy/oauth/authorize?
  client_id=${CLIENT_ID}&
  response_type=code&
  redirect_uri=${REDIRECT_URI}

The customer will first log in to their Nomos account if not already authenticated. After authentication, they will be shown a consent screen explaining what data your application is requesting access to.

3

Handle the callback

After the customer authenticates and approves your application, we’ll redirect them back to your redirect_uri with an authorization code:

https://your-app.com/callback?code=${AUTHORIZATION_CODE}

This code is short-lived (valid for 10 minutes) and can only be used once to obtain access tokens.

4

Exchange for tokens

Exchange the authorization code for access and refresh tokens by making a request from your backend server:

curl -X POST https://api.nomos.energy/oauth/token \
  -H "Authorization: Basic $(echo -n '${CLIENT_ID}:${CLIENT_SECRET}' | base64)" \
  -d grant_type=authorization_code \
  -d code=${AUTHORIZATION_CODE} \
  -d redirect_uri=${REDIRECT_URI}

The response will include an access token (valid for 60 minutes) and a refresh token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1B4a2e77838347a7E420ce178F2E7c6912E169246c"
}
5

Make authenticated requests

Include the access token in the Authorization header of your API requests:

curl -X GET https://api.nomos.energy/subscriptions \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
6

Refresh expired tokens

When the access token expires, use the refresh token to obtain a new one:

curl -X POST https://api.nomos.energy/oauth/token \
  -H "Authorization: Basic $(echo -n '${CLIENT_ID}:${CLIENT_SECRET}' | base64)" \
  -d grant_type=refresh_token \
  -d refresh_token=${REFRESH_TOKEN}
Client Credentials GrantBuild Your Own Checkout