The Nomos API uses the OAuth 2.0 Authorization Framework for authentication. Each organization can create multiple applications, with each one having its own set of client credentials.

To get started with a new project, reach out to us at support@nomos.energy.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

​
Overview

Nomos supports two main authentication flows for obtaining access tokens:

Client Credentials Grant

Best for server-to-server API requests. Use your client credentials to authenticate directly with the API.

Authorization Code Grant

For third-party integrations (such as third-party HEMS providers) requiring user consent to access the API on their behalf.

​
Token Lifecycle

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

​
Error Handling

If there’s an issue with authentication or authorization, such as a missing or expired token, the API will return a 401 HTTP response.

For example, if your access token is expired:

{
  "object": "error",
  "type": "unauthenticated",
  "message": "The access token is expired."
}

For more details on error codes, see the Error Codes page.

Error CodesClient Credentials Grant