FAQ

Table of contents:

Is there a demo account?

Yes, we have a sandbox account with demo data set up where you can try out all API end points. Get in touch with us for the credentials.

How does the authentication work?

For our service to be able to acknowledge and process your requests, a token has to be sent along. To increase security the token only has a limited validity. You can try it out directly in your browser as soon as you have an account or ask for the sandbox credentials. We prepared a step-by-step guide for the browser UI.

How can I try out the API requests in my browser?

You may either contact us for sandbox account credentials or when you sign up to our service provide us with one or more email addresses for setting up user accounts.

1. Click on the Authorize button on the API page.
   
2. Tick the checkbox for user_impersonation and click Authorize
   
3. Fill in your email address (if you have logged in before, this will be skipped)
   
4. Fill in your account password (if you have logged in before, this will be skipped)
   
5. Click Close
   
6. When the padlock icon is closed now, you are ready to try out the API requests from your browser
   
7. Expand the section of /chargepointoperator and click on Try it out
   
8. You can directly edit the sample JSON data before you send it to the server. Then click Execute

9. Now we can see the response of the server.

   • Marked red is the HTTP status code. Each number has a specific meaning. 201 means a new record was created successfully.
   • Marked green is the body of the server response. It returns the full ChargePointOperator record as a JSON dictionary.
   • Marked blue is the curl command that you can use in a terminal to trigger the same request again. As you can see the browser inserted the token obtained from the login automatically. Keep in mind that it is only valid for no longer than one hour.
     

What are access tokens and refresh tokens?

• Access tokens are required for all API requests. If no access token or an invalid access token is given our service cannot authorize nor identify you and will respond with a HTTP status of 403 (= unauthorized). They are valid for a maximum of one hour.
• Refresh tokens are used to retrieve new access tokens without human interaction. They are valid for 90 days and get renewed automatically each time you use one.

How can I obtain access and refresh tokens for automated processes?

We utilize the Microsofts OAuth 2.0 device authorization grant flow specifically for devices with limited or no input capabilities. Have a look at the following sample snippets. They require two basic terminal tools: curl and jq. Of course you may simply adapt the code for any other tool that can make HTTP requests and read JSON data.

You can download the entire bash sample script comprising of an extended version of the three snippets here. It will fetch tokens and use them to create a new charge point operator.

Code snippet 1: Getting access and refresh token:

This bash snippet shows you how you can obtain token after a one-time human login that afterwards allows your script/automation to obtain further tokens without human interaction. The validity of the refresh token is extended each time you use it to 90 days. For security this standard does not allow obtain tokens without prior human login.

#!/bin/bash

client_id=446782de-6e26-457a-a4b0-1f7cabfad2fd
tenant_id=f7731598-1da9-4b5f-a888-ceaf1d14fae0

fetch_token () {
    response=$(curl -s https://login.microsoftonline.com/${tenant_id}/oauth2/v2.0/devicecode \
        -d 'scope='$client_id'/user_impersonation offline_access&client_id='$client_id)

    device_code=$(printf '%s' "$response" | jq -r .device_code)
    user_code=$(printf '%s' "$response" | jq .user_code)

    echo "Enter the user code $user_code on https://microsoft.com/devicelogin"
    read -p "Press any key to continue afterwards."
    response=$(curl -s https://login.microsoftonline.com/${tenant_id}/oauth2/v2.0/token \
        -d 'grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id='$client_id \
        -d '&device_code='$device_code)

    access_token=$(printf '%s' "$response" | jq -r .access_token)
    refresh_token=$(printf '%s' "$response" | jq -r .refresh_token)

    echo "Access token: $access_token"
    echo "-------"
    echo "Refresh token: $refresh_token"
    echo ""
}

fetch_token

1. Lets run it:

   ./snippet1.sh
   Enter the user code "DXXXXXXX9" on https://microsoft.com/devicelogin
   Press any key to continue afterwards.
   

2. At this stage open https://microsoft.com/devicelogin and follow the instructions there:

1. Press any key in the terminal and the script will continue to obtain the tokens and output them on the screen:

   Access token: eyJ0eXAiOm9pZCI6clL7al69TWihRqH6U0fYPi...(shortened)...shyIjG
   -------
   Refresh token: 0.AV0AmBVz96kdX0uoiM6vHRT64HmsDRTD3JQ...(shortened)...CPLXm9
   

You can use these two tokens now in any of your automations/scripts without further human interaction.

Code snippet 2: Refreshing tokens

In the previous snippet we have obtained both an access and a refresh token. Since the access token will expire latest 60 minutes after obtaining it, we now show how to make use of the refresh token. You may obtain a new access token at any time, you don't need to wait for expiration of the previous one.

Add this to the sample snippet 1 and run it:

    response=$(curl -s https://login.microsoftonline.com/${tenant_id}/oauth2/v2.0/token \
         -d 'refresh_token='$refresh_token \
         -d '&grant_type=refresh_token&scope='$client_id'/user_impersonation offline_access')

    access_token2=$(printf '%s' "$response" | jq -r .access_token)

    echo "Access token2: $access_token2"

It should provide you with a brand new access token.

Code snippet 3: Fetching the ChargePointOperator list

Now we want to put the access token to actual use and fetch all charge point operators of our account. Add this to the snippet 1 (you don't need snippet 2 for this):

    curl -s https://qaas-chargingpoints.azurewebsites.net/chargepointoperators \
        -H "accept: application/json" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $access_token" | jq .

Here is a sample output of the response, a list of two charge point operators as a list of JSON objects:

    [
     {
         "id": 335,
         "created": "2022-09-28T22:05:59Z",
         "last_updated": "2022-09-28T22:05:59Z",
         "organization_name": "Beispiel GmbH",
         "street": "Baumstraße 1",
         "zip_code": "85123",
         "town": "Entenhausen",
         "terms_agreed": "2022-09-28T15:38:21Z",
         "customer_reference": "AB-123"
     },
     {
         "id": 336,
         "created": "2022-09-28T22:07:41Z",
         "last_updated": "2022-09-28T22:07:41Z",
         "organization_name": "Mustermann GmbH",
         "street": "Musterstraße 1",
         "zip_code": "34223",
         "town": "Duckberg",
         "terms_agreed": "2022-09-28T15:39:34Z",
         "customer_reference": "AB-124"
     }
    ]

Can I edit a charge point record?

Yes, you may change the amount via a PATCH-request but only before the record reached the status sent_to_uba. Once we have submitted it to the Umweltbundesamt, we cannot allow modifications of the record as it would invalidate our communication with the ministry..

What is the meaning of the HTTP status codes that the API returns?

May I use an additional account as a test environment / sandbox?

Yes, we are happy to provide you a 2nd account where you can try out your processes and make requests as you wish without incurring costs. For that please provide us with a email address that is not registered as user in your main account.

Can the API execute a webhook when a status update occurs?

Not at the moment, but we want to introduce this as a feature in the future.