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.

PKCE (Proof Key for Code Exchange) is optional for the Authorization Code flow. If you decide to use it, you have to include both of these additional parameters:

  • code_challenge: A code challenge derived from your code verifier
  • code_challenge_method: Either “S256” (recommended) or “plain”
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"
}

When using PKCE, you must include the code_verifier in the token request. The code verifier must:

  • Be between 43 and 128 characters long
  • Only contain alphanumeric characters and ’-’, ’.’, ’_’, ’~’
  • Match the code challenge method used in the authorization request
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}

​
PKCE Implementation Details

PKCE (Proof Key for Code Exchange) is a security extension to the OAuth 2.0 Authorization Code flow that prevents authorization code interception attacks. It is defined in RFC 7636. Here’s how to implement it:

  1. Generate a Code Verifier:

    • Create a random string between 43 and 128 characters
    • Use only alphanumeric characters and ’-’, ’.’, ’_’, ’~’
    • Store this securely in your application

  2. Create a Code Challenge:

    • If using code_challenge_method="S256" (recommended):
      • Hash the code verifier with SHA-256
      • Base64url encode the hash
    • If using code_challenge_method="plain":
      • Use the code verifier directly as the challenge

  3. Include in Authorization Request:

    • Add code_challenge and code_challenge_method to the authorization URL
    • Keep the code verifier secure until the token exchange

  4. Token Exchange:

    • Include the original code verifier in the token request
    • The server will validate that the verifier matches the challenge

We strongly recommend using the S256 code challenge method as it provides better security than the plain method.