Skip to main content
The Nomos API uses the OAuth 2.0 Authorization Framework for authentication. Each organization can create multiple applications, and each application has its own set of client credentials. To get started, contact support@nomos.energy to obtain your client_id and client_secret.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
Keep your client_secret secure and never expose it in client-side code. Don’t hardcode it in code repositories and don’t share it with others.

​
Choosing a flow

Nomos supports two OAuth 2.0 flows. Pick the one that matches how your application will access the API:

​
Token lifecycle

  • Access tokens are valid for 60 minutes.
  • Use the refresh token to obtain a new access token when it expires.
  • Include the access token in the Authorization header of every request:
curl -X GET https://api.nomos.energy/ \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

​
Client Credentials Grant

The Client Credentials Grant is the standard OAuth 2.0 flow for server-to-server API requests (RFC 6749 §4.4). Your server authenticates directly with our API using your client credentials, without any user interaction.
1

Get your credentials

Contact support@nomos.energy to obtain your client_id and client_secret.
2

Exchange for tokens

Exchange your client credentials for access and refresh tokens by making a request from your backend server. The client_id and client_secret must be sent in the Authorization header as Basic authentication credentials:
curl -X POST https://api.nomos.energy/oauth/token \
  -H "Authorization: Basic $(echo -n '${CLIENT_ID}:${CLIENT_SECRET}' | base64)" \
  -d grant_type=client_credentials
The response includes an access token (valid for 60 minutes) and a refresh token:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1B4a2e77838347a7E420ce178F2E7c6912E169246c"
}
3

Make authenticated requests

Include the access token in the Authorization header:
curl -X GET https://api.nomos.energy/subscriptions \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
4

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}

​
Authorization Code Grant

The Authorization Code Grant 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 the right choice when you need customer consent — for example, when a third-party Home Energy Management System (HEMS) retrieves price information for a customer’s subscription. The customer authenticates with Nomos and explicitly grants your application access to their data.
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, 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 includes 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:
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

PKCE (Proof Key for Code Exchange) is a security extension to the Authorization Code flow that prevents authorization code interception attacks (RFC 7636).
  1. Generate a code verifier.
    • Create a random string between 43 and 128 characters.
    • Use only alphanumeric characters and -, ., _, ~.
    • Store it securely in your application.
  2. Create a code challenge.
    • With code_challenge_method=S256 (recommended): hash the code verifier with SHA-256, then base64url-encode the hash.
    • With code_challenge_method=plain: use the code verifier directly as the challenge.
  3. Include it in the authorization request.
    • Add code_challenge and code_challenge_method to the authorization URL.
    • Keep the code verifier secure until the token exchange.
  4. Send the verifier on token exchange.
    • Include the original code verifier in the token request.
    • The server validates that the verifier matches the challenge.
We strongly recommend S256 over plain — it provides materially better security.

​
Error handling

If there’s an issue with authentication or authorization (such as a missing or expired token), the API returns a 401 HTTP response. For example, if your access token is expired: 
{
  "object": "error",
  "type": "unauthenticated",
  "message": "The access token is expired."
}
For the full list of error codes, see Errors.