How-to

This page contains useful how-to's for connecting your client application to Vattenfall Energy Trading Services.

How to get test access to the provided APIs?

Just send us an e-mail with the products or concrete APIs that you would like to consume. We will then grant permission for you (essentially create CLIENT-ID and CLIENT-SECRET to be used with the OpenID Connect flow - see below).

How to authorize?

All APIs use OpenID Connect standard to authenticate and authorize client systems.

How to fetch a Bearer Token?

Before an API can be consumed, clients need to fetch a Bearer Token from the Authorization Service. To fetch a token the following request needs to be sent to the Authorization Server:

curl --location --request POST 'https://vattenfall-flexibility-services.azure-api.net/token' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=client_credentials' \
     --data-urlencode 'client_id=<CLIENT-ID>' \
     --data-urlencode 'client_secret=<CLIENT-SECRET>'
     --data-urlencode 'scope=openid'

The values for CLIENT-ID and CLIENT-SECRET will be provided by Vattenfall. The following URLs of the Authorization Server can be used for fetching the tokens:

Test system

https://vattenfall-flexibility-services-tst.azure-api.net/token

Production system

https://vattenfall-flexibility-services.azure-api.net/token

The HTTP response object contains the Bearer Token in the field access_token:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIi...",
    "expires_in": 300,
    "refresh_expires_in": 28800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwi...",
    "token_type": "bearer",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIi...",
    "not-before-policy": 0,
    "session_state": "4382d2e5-f268-4a24-840b-99578dbcc9f6",
    "scope": "openid"
}

The token is valid until it expires. Upon expiry tokens can be refreshed with a new life-span. An access_token expires in 5 minutes. A refresh token has a life-span of 8 hours.

How to use a Bearer Token to authenticate with our APIs?

Once you have fetched a valid Bearer Token (access_token - see above) you can consume our APIs by passing it as an Authorization header. For instance fetching the final schedule for an asset with id 12345 you would have to send this:

curl -X GET "https://vattenfall-flexibility-services.azure-api.net/schedule/api/schedule/12345" \
     -H "accept: */*" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIi..."

The URL for all APIs is prefixed with:

Test system

https://vattenfall-flexibility-services-tst.azure-api.net/<API-NAME>/api/...

Production system

https://vattenfall-flexibility-services.azure-api.net/<API-NAME>/api/...

HINT: You can look up all specific details about our API endpoints and paths within the "Try it" section of each API operation. There you can also compose and submit any request in an interactive way.

How to provide data as input for the optimization?

This sequence diagram shows a reference data flow for the Asset Data product.

How to get the results of the optimization and trading?

This sequence diagram shows a reference data flow for the Trading product.

How to get access to different kind of data?

This sequence diagram shows a reference data flow for the Time Series product.