Skip to main content

Authentication

The Exnaton API uses OAuth2 Authorization Code Flow for authentication. This is the standard flow used by third-party applications like Home Assistant.

Using OAuth2 Libraries​

Most programming languages have OAuth2 libraries that handle the authorization flow automatically. If you're using an existing OAuth2 library, it likely supports this flow out of the box with the right configuration parameters.

Configuration Parameters​

When configuring your OAuth2 library, use these parameters:

  • Authorization URL: $EXNATON_URL/api/oauth2/auth
  • Token URL: $EXNATON_URL/api/oauth2/token
  • Discovery endpoint: $EXNATON_URL/api/oauth2/.well-known/openid-configuration
  • Client ID: exnaton-public
  • Redirect URI: Your registered redirect URI
  • Scope: email profile (or as specified by Exnaton)

The redirect URI is a crucial part of the OAuth2 flow:

  • It must be registered with Exnaton
  • It must match exactly between the authorization request and token exchange
  • It tells the OAuth2 server where to send the authorization code after the user grants permission
  • It helps prevent authorization code interception attacks

For example, if you're developing a local application, your redirect URI might be:

http://localhost:8123/auth/external/callback

Manual OAuth2 Implementation​

If you need to implement the OAuth2 flow manually or want to understand how it works, here's the detailed process:

OAuth2 Flow Steps​

The flow works as follows:

  1. Your application sends a request to our authorization endpoint, which redirects the user to a log in page.
EXNATON_URL/api/public-auth/oauth2/auth?client_id=exnaton-public&response_type=code&scope=email+profile&redirect_uri=YOUR_REDIRECT_URI

  1. The user logs in and grants permission to your application

  2. We redirect back to your application with an authorization code. The response will be a redirect to your redirect URI with the code as a query parameter:

YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE

For example:

EXNATON_URL?code=ory_ac_U8koNU0pqd9SCrMR2pbb9fWK7f_nDJY3uQ4o68-HPFw.fINsE_NiS8zupQf3wzqT3afwTJSIAOieGQpfDvew0xY
  1. Your application exchanges this code for an access token hitting the OAuth2 token endpoint. Example with curl:
curl --request POST \
  --url "$EXNATON_URL/api/oauth2/token" \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&client_id=exnaton-public&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI'
  1. The response will contain your access token:
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

Making API Requests​

Once you have obtained an access token, you can make requests to the API. All requests must include the access token in the Authorization header.

curl --request GET \
  --url "$EXNATON_URL/api/public/accounts/{id}/rate/current" \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

The response will be in the following format:

{
  "metadata": {
    "interval": "string",
    "currency": "EUR"
  },
  "data": {
    "timestamp": "string",
    "value": number | null
  }
}

Available Endpoints​

  • Get Energy Rate - Complete Rate Calculation: Returns total energy rate per kWh. Aggregates future market rates and the user's rate plans.

  • Current Energy Rate - Real-Time Market Rate: Returns market energy rate per kWh. Reflects the most recent rate based on the fastest-changing component from the user's rate plans.

  • Get Current Base rate - Fixed Infrastructure Rate: Returns the currently valid base rate per billing period. These are regulatory and infrastructure costs separate from variable energy commodity pricing. Each endpoint requires your account ID in the URL path and your access token in the Authorization header.

Token Expiration​

The access token expires after the time specified in the expires_in field (in seconds). When the token expires, you'll need to use the refresh token to obtain a new access token.

Security Best Practices​

  1. Keep your client credentials and access tokens secure
  2. Use HTTPS for all API requests
  3. Rotate your credentials periodically
  4. Use the minimum required permissions
  5. Revoke any credentials that are no longer needed

Managing Credentials (TODO)​

You can manage your credentials from your account settings:

  • View all active access tokens
  • Revoke existing credentials
  • See when each credential was last used