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.

The Nomos API uses OAuth 2.0. You’ll need a client_id and client_secret issued to your organization. Keep the secret server-side. Most integrations use the Client Credentials flow for server-to-server access against your own organization’s data. If your app instead acts on behalf of a customer (for example, a HEMS provider reading prices for a specific subscription), use the Authorization Code flow.

​
Client Credentials Grant

Server-to-server flow against your own organization’s data (RFC 6749 §4.4). No customer interaction is involved.

​
Request a token

curl -X POST https://api.nomos.energy/oauth/token \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -d grant_type=client_credentials
/oauth/token responds with: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "21cc84a3ad98736f4e5eddc88a1f4b58a29ae96206027c9b59d874cb2a7f7e02"
}

​
Use the access token

Send it in the Authorization header on every API request: 
curl https://api.nomos.energy/subscriptions \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

​
Refresh

Access tokens last 60 minutes. When yours expires, exchange the refresh token at /oauth/token for a new pair: 
curl -X POST https://api.nomos.energy/oauth/token \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -d grant_type=refresh_token \
  -d refresh_token=${REFRESH_TOKEN}

​
Authorization Code Grant

If your app acts on a customer’s behalf instead of running server-to-server, use this flow (RFC 6749 §4.1). The token response, header usage, and refresh model are identical to Client Credentials; only the way you obtain the initial token differs. Your callback URI must be registered against your client_id; subpaths under the registered origin are accepted.
1

Redirect the customer to /oauth/authorize

https://api.nomos.energy/oauth/authorize?
  client_id=${CLIENT_ID}&
  response_type=code&
  redirect_uri=${REDIRECT_URI}&
  state=${STATE}
state is a per-request opaque value you generate, store, and verify on callback (CSRF protection).
For PKCE, also send code_challenge and code_challenge_method (use S256). Public clients (no client_secret) must use PKCE.
While the redirect is open, the customer signs in and grants consent on Nomos-hosted screens. See the third-party login guide for the customer journey.
2

Handle the callback

Nomos redirects with a single-use code (10-minute TTL) and your state. Reject the callback if state doesn’t match.
https://your-app.com/callback?
  code=${AUTHORIZATION_CODE}&
  state=${STATE}
3

Exchange the code at /oauth/token

curl -X POST https://api.nomos.energy/oauth/token \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -d grant_type=authorization_code \
  -d code=${AUTHORIZATION_CODE} \
  -d redirect_uri=${REDIRECT_URI}
For PKCE, also send code_verifier.

​
PKCE

PKCE (Proof Key for Code Exchange) hardens the flow against code interception (RFC 7636). Prefer S256 over plain.
1

Generate a verifier and challenge

Pick a random code_verifier of 43–128 characters from [A-Za-z0-9-._~]. With S256, the code_challenge is the base64url-encoded SHA-256 of the verifier; with plain, it’s the verifier itself.
2

Send the challenge on /oauth/authorize

Add code_challenge and code_challenge_method to the authorize URL.
3

Send the verifier on /oauth/token

Include the original code_verifier in the token request. Nomos validates it against the challenge.
Auth failures return 401 UNAUTHORIZED with the standard error envelope. See Errors for the response shape and common causes.