☰Authentication and Authorization
On this page we will explain how you gain access to the Loqio API and how your applications can make requests on our customers behalf. To make requests to the API you will need two keys or tokens.
The first is a API key. This API key can be obtained by creating an account on this site and then creating a subscription to our API. At the moment this subscription is free and does not have any limits on the number of requests that can be made within sensible rate limits. Do note that we may introduce paid subscription tiers in the future. You will need one API key for your application regardless of the number of customers that use your apps.
The second set of keys are private keys used to login to our platform and gain access to our customers data and make requests on their behalf. These keys are created per customer and each customer will have their own set of keys.
API Keys
To request an API key first create an account on this site by clicking the "Sign up" link in the top right corner and following the instructions. You will need to activate your account via an e-mail you receive before you can continue.
After you've activated your account login if needed and then click on the "Products" link in the top menu. Select the "Loqio Energy Management" product by clicking the link.
Now you will see a form asking you for a name of your subscription and a "Subscribe" button. Enter a name and click the subscribe button to create a subscription. This name can be anything and is for your own internal use.
After you have created a subscription, we will receive a notification and will need to approve the subscription. Once we have approved your subscription request you will receive an e-mail letting you know you can continue.
While you wait for the subscription request to be approved you can start with exploring the rest of the documentation and the API schema.
After your subscription has been activated come back to this website and sign in if needed. Then click the "Profile" button. On your profile you will see a list of subscriptions that should now list your subscription as active.
Each subscription has two sets of keys. A primary and a secondary key. You can use either one of the keys to make requests to our API. Click on "Show" to reveal the key. If you for some reason need to regenerate the key, click on "Regenerate". This will invalidate your old key and create a new key to use. This will take effect immediately so be careful clicking this button as the old key will stop working. It is best to first switch to using the secondary key and then regenerate the primary key.
Making requests
The API key must be included in every request made to our API. Not including the API key will result in an error. To include the key add a header to each request. The header name must be: Ocp-Apim-Subscription-Key and the value the primary or secondary key for your subscription.
Authentication
Most API requests need authentication and to make these requests you need to receive a set of client credentials and exchange these credentials for an access token. A set of client credentials is linked to a customer in our platform. If your app services multiple customers on our platform you will need to get a set of credentials for each individual customer.
Make sure to keep these credentials safe and do not share them with anyone. These credentials are linked to your application, and you are responsible for anything that is done with them. If for any reason somehow the client credentials get compromised contact us immediately in order to invalidate the credentials and receive a new set of credentials.
To make api requests on your customers behalf you request an access token with these client credentials. While the client credentials do not expire the access token has a limited lifetime and needs to be refreshed before it expires. Do not expose your client credentials in any client facing / frontend application in any way.
To request an access token you will need to make a request to our IDP platform. The base URL for the IDP platform is: https://idp.loqio.app.
Requesting a token
To request an access token make a POST request to: https://idp.loqio.app/oauth/v2/token. In the headers include the content_type, grant_type and scopes. Authenticate the request using Basic Authentication using the ClientId as username and ClientSecret as password.
The grant_type should be set to client_credentials
The scopes should include: openid profile urn:zitadel:iam:org:project:id:272704118332588199:aud urn:zitadel:iam:org:id:{orgId} urn:zitadel:iam:user:metadata
The {orgId} part of the scopes needs to be replaced with the organizationId of the customer you are making requests for. You will receive this Id together with the client credentials.
Example request using curl
curl --request POST \--url https://idp.loqio.app/oauth/v2/token \--header 'Content-Type: application/x-www-form-urlencoded' \--data grant_type=client_credentials \--data scope='openid profile urn:zitadel:iam:org:project:id:272704118332588199:aud urn:zitadel:iam:org:id:{orgId} urn:zitadel:iam:user:metadata' \--user "$CLIENT_ID:$CLIENT_SECRET"
You should receive a successful response with access_token, token_type and time to expiry in seconds as expires_in.
{"access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...","token_type": "Bearer","expires_in": 43199}
The string under access_token must be included in any API requests as Bearer token in the Authorization header.
Client Identification
Our API requires client identification headers to be present in each request. This way we can identify which clients are using our API and which queries and mutations are used. No data contained in the queries and mutations are stored. This way we can notify API users of any (breaking) changes to the api that are going to impact their integrations.
Include the following two headers with each request: Graphql-Client-Name and Graphql-Client-Version with the correct values. The name should be descriptive of your application.