Authentication

All our API endpoints are protected and require authentication. If you have access to Monta Partner API you can find your credentials in the Monta Portal.

You might have multiple credentials with different scopes in case you requested them.

Access Token

To obtain your access token - needed for all subsequent requests - you have to call our /auth/token endpoint and provide your clientId and clientSecret.

If your request was successful, you'll receive a response like this:

{
  "accessToken": "4596d494-5f6c-4f87-aed5-db68240a58dd",
  "refreshToken": "bbf8c0ed-dbb0-434f-8512-ab24eb64c46a",
  "accessTokenExpirationDate": "2023-02-16T07:53:02.059724728Z",
  "refreshTokenExpirationDate": "2023-02-17T06:53:02.059733860Z"
}

For subsequent requests you have to use the accessToken for authentication. Pass it to the Authorization header as Bearer token:

Authorization: Bearer 4596d494-5f6c-4f87-aed5-db68240a58dd

💡

Make use of Refresh Token flow!

As you can see the accessToken will expire within 1 hour. To protect your clientId and clientSecret you should make use of the refreshToken and Refresh Token flow to obtain a new one.

Refresh Token flow

To refresh your access token you have to call our /auth/refresh endpoint and provide your refreshToken.

If your request was successful, you'll receive a new set of access and refresh tokens:

{
  "accessToken": "fbf6d41f-f8cf-491f-bc52-481dd6829ef2",
  "refreshToken": "b596a1fb-9c9f-4cca-8bd0-409b7f21c597",
  "accessTokenExpirationDate": "2023-02-16T07:56:02.059724728Z",
  "refreshTokenExpirationDate": "2023-02-17T06:56:02.059733860Z"
}

Access Control

Depending on your credentials setup, you will have access to either:

• all resources within your operator account
• OR all resources from defined teams only within your operator account

On top of this your credentials might be limited to specific scopes:

Scopes

A scope contains an entity scope and a permission, ie. charge-points:read

Currently there are 3 permission scopes:

• read
• write
• delete

They inherit from each other, so delete allows to read and write as well.

Examples

• charge-points:read - you can only read charge points.
• charge-points:write - all of :read
  plus
  you can create and update them.
• charge-points:delete - all of :write
  plus
  you can delete access charge points.

Full Access:

• all:delete - you can access and modify any resource

💡

Use different scopes to control access and mitigate risk

Depending on your needs it might make sense to have various credentials for different scopes that you can share with different teams within your company. E.g. it might be sufficient to give your finance team / tool credentials limited to wallet-transactions scope while your product team has a more broad access level to control charges and display charge points within your products.

You can use the /auth/me endpoint to receive information about the scope, restrictions on teams etc. As sample response looks like:

{  
  "name": "Partner API Demo",  
  "operatorId": 42,  
  "teamIds": [],  
  "clientId": "73d86c7f-48de-4a0f-bd3c-da243e16b630",  
  "rateLimit": 1000,  
  "rateLimitIntervalInSeconds": 600,  
  "scopes": [  
    "all:delete"  
  ]  
}

This credential has access to all resources within operator with id 42 (no restrictions on teamIds). Since the scopes collection contains all:delete, you can call any of our endpoints with this.