Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nomos.energy/llms.txt

Use this file to discover all available pages before exploring further.

When a third-party application — a HEMS, an EV charger, a home-automation hub — needs to read or act on a Nomos customer’s data, the customer logs in with their Nomos credentials on a Nomos-hosted page and explicitly grants your application access. We hand back an access_token and refresh_token your backend stores against the customer’s account. Once you have the tokens, continue with Load shifting and optimization to pull prices and drive flexible loads.
This is the right flow if you act on behalf of a customer (third-party HEMS and similar). If you’re Nomos’s own organization and just need server-to-server access to your own data, use the Client Credentials flow instead.

​
Prerequisites

  • A client_id and client_secret for your application. Email support@nomos.energy to register.
  • One or more redirect URIs pre-registered with us. That’s where customers come back to after consenting.

​
1. Send the customer to authorize

Send the customer to our authorization endpoint. They’ll log in with their Nomos credentials and explicitly approve your application having access: 
https://api.nomos.energy/oauth/authorize?
  client_id=${CLIENT_ID}&
  response_type=code&
  redirect_uri=${REDIRECT_URI}
We redirect back to your redirect_uri with a single-use authorization code: 
https://your-app.example/callback?code=abc123
Always layer PKCE on top; even on the server, it’s free protection against code interception.

​
2. Exchange the code for tokens

From your backend, exchange the authorization code for tokens: 
const res = await fetch("https://api.nomos.energy/oauth/token", {
  method: "POST",
  headers: {
    Authorization: `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: authorizationCode,
    redirect_uri: REDIRECT_URI,
    code_verifier: codeVerifier,
  }),
});

const { access_token, refresh_token, expires_in } = await res.json();
Store the refresh_token securely against the customer’s account; you’ll use it to keep the integration alive indefinitely.

​
3. Refresh tokens before they expire

Access tokens are valid for 60 minutes. Use the refresh token to mint new ones: 
const res = await fetch("https://api.nomos.energy/oauth/token", {
  method: "POST",
  headers: {
    Authorization: `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "refresh_token",
    refresh_token,
  }),
});
We rotate refresh tokens on every refresh; always store the new one. If a refresh fails with UNAUTHORIZED, the customer has revoked access — send them through the authorize step again. The full token lifecycle, including PKCE details, is documented under Authentication.

​
What’s next

Load shifting and optimization

Now that you have an access token, pull the customer’s 15-minute prices and drive their flexible loads into the cheap intervals.

Authentication deep dive

Full Authorization Code + PKCE reference, including token rotation and error handling.