Authentication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

The ev.energy API uses Oauth 2 for authentication. Depending on the nature of your integration, you will either want to use the Authorization code method or the Client credentials method.

Authorization code method

The authorization code grant type allows you to make requests to the API on behalf of a user.

Initial Setup

1. Give us the name you want your app to be identified as (the view your users will see will say 'Authorize your_app_name?'), the types of user data you want to access, and the redirect URI you want to be redirected to once a user has completed authorization, e.g. https://yoursite.com/your-callback-url.

2. We will create an OAuth application for you with these details and scopes and provide you with a client ID and client secret.

Authorization and token acquisition

⚠ Security for Native and SPA clients

This section describes the authorization_code flow using a client secret. If your app cannot keep a client secret secure (eg. because it is a native app, or single page web app), or you want to further protect your implementation, see the "Implementing PKCE" section below.

1. Users can authorize your app to access EV energy data at the URL below. This will first take them to an EV energy login page if they are not yet authenticated, and then to the authorization page listing the scopes you are requesting from them.

   https://api.ev.energy/o/authorize/?response_type=code&client_id=your_client_id&redirect_uri=your_redirect_uri

2. Once they have authorized, they will be redirected to the callback page you provided with an authorization code as a query param, e.g. https://yoursite.com/your-callback-page?code=i8u3oRHEXajKcwzPgmujDbtMvDpaDs. This authorization code is valid for 1 minute.

3. Make a post request to the token endpoint to get an access token. An example using curl:

   curl -X POST
   -H "Cache-Control: no-cache"
   -H "Content-Type: application/x-www-form-urlencoded"
   "https://api.ev.energy/o/token"
   -d "client_id=<your_client_id>"
   -d "client_secret=<your_client_secret>"
   -d "code=<your_authorization_code>"
   -d "redirect_uri=<your_redirect_uri>"
   -d "grant_type=authorization_code"

   This will return a response like this:

   {
     "access_token": "ELf3uR6tEyRFaL1mLVFmsAEfNZLpso",
     "expires_in": 36000,
     "token_type": "Bearer",
     "scope": "charging_session:read vehicle:read",
     "refresh_token": "EgYR8vafiT0CgurFrU9yajj89K2z2n"
   }

Implementing PKCE

PKCE is an extension to Oauth to prevent CSRF and authorization code injection attacks.

1. Before crafting the URL that the user will authorise with, you will need to generate a "code verifier" and a "code challenge". In Python you can do that like this:

   import random
   import string
   import base64
   import hashlib
   
   code_verifier = ''.join(random.choice(string.ascii_uppercase + string.digits) for _ in range(random.randint(43, 128)))
   code_verifier = base64.urlsafe_b64encode(code_verifier.encode('utf-8'))
   
   code_challenge = hashlib.sha256(code_verifier).digest()
   code_challenge = base64.urlsafe_b64encode(code_challenge).decode('utf-8').replace('=', '')

   You can find examples to do this in various other common languages in Auth0's docs here or find the requirements to implement it yourself here.

2. Craft the URL for the user to authorise with and include the code challenge:

   https://api.ev.energy/o/authorize?response_type=code&client_id=your_client_id&redirect_uri=your_redirect_uri&code_challenge=your_code_challenge&code_challenge_method=S256

3. Once they have authorized, they will be redirected to the callback page you provided with an authorization code as a query param, e.g. https://yoursite.com/your-callback-page?code=i8u3oRHEXajKcwzPgmujDbtMvDpaDs. This authorization code is valid for 1 minute.

4. Make a post request to the token endpoint to get an access token, including your code verifier so the server can check that you are the same client that requested the authorisation code.

   curl -X POST
   -H "Cache-Control: no-cache"
   -H "Content-Type: application/x-www-form-urlencoded"
   "https://api.ev.energy/o/token"
   -d "client_id=<your_client_id>"
   -d "code=<your_authorization_code>"
   -d "code_verifier=<your_code_verifier>"
   -d "redirect_uri=<your_redirect_uri>"
   -d "grant_type=authorization_code"

   This will return a response like this:

   {
     "access_token": "ELf3uR6tEyRFaL1mLVFmsAEfNZLpso",
     "expires_in": 36000,
     "token_type": "Bearer",
     "scope": "charging_session:read vehicle:read",
     "refresh_token": "EgYR8vafiT0CgurFrU9yajj89K2z2n"
   }

Using the API

You will then be able to make requests to the API endpoints that your scopes permit by adding "Bearer your_access_token" to the request's Authorization header.

Client credentials method

The client credentials grant type allows you to authorise as a single individual or organisation, depending on how it has been configured.

Initial Setup

1. Make sure your users have consented to share their ev.energy data with you (including the specific types of data you will request).

2. Give us the types of user data you want to access and we will create an OAuth application for you with these scopes and provide you with a client ID and client secret.

Authorization and token acquisition

1. Encode your client ID and client secret in base64 for HTTP basic authentication, e.g. in python:

   import base64
   
   client_id = "<your_client_id>"
   client_secret = "<your_client_secret>"
   credential = f"{client_id}:{client_secret}"
   print(base64.b64encode(credential.encode("utf-8")))

2. Make a post request to the token endpoint to get an access token. An example using curl:

   curl -X POST
   -H "Authorization: Basic <your_base64_encoded_credential>"
   -H "Cache-Control: no-cache"
   -H "Content-Type: application/x-www-form-urlencoded"
   "https://api.ev.energy/o/token"
   -d "grant_type=client_credentials"

   This will return a response like this:

   {
     "access_token": "sUfQGMmfIrfrrUhcdMBrz1rrQzD2l8",
     "expires_in": 36000,
     "token_type": "Bearer",
     "scope": "charging_session:read vehicle:read",
   }

Using the API

You will then be able to make requests to the API endpoints that your scopes permit by adding "Bearer your_access_token" to the request's Authorization header. You will be able to access data for any of your users.

Refreshing a Token

Tokens expire after 10 hours. To obtain a new one make a call to the tokens endpoint with your refresh token, e.g.

curl -X POST
-H "Cache-Control: no-cache"
-H "Content-Type: application/x-www-form-urlencoded"
"https://api.ev.energy/o/token"
-d "client_id=<your_client_id>"
-d "client_secret=<your_client_secret>"
-d "refresh_token=<your_refresh_token>"
-d "grant_type=refresh_token"

Revoking a Token

To revoke an access or refresh token:

curl -X POST
-H "Cache-Control: no-cache"
-H "Content-Type: application/x-www-form-urlencoded"
"https://api.ev.energy/o/revoke_token"
-d "client_id=<your_client_id>"
-d "client_secret=<your_client_secret>"
-d "token=<token>"

Note: the trailing slash on this URL is required. You will receive a 405 error without it.