Authentication

The Control API uses OpenID Connect with the OAuth 2.0 standard for authenticating access tokens. Your access token authorizes you to use the Control REST API.

This is the endpoint used for production environments:

Copy
Copied
https://id.aritma.io/connect/token
Note:

For development use: https://id.dev.aritma.io/connect/token

Scopes

Scope Description
reconcile Access to the Control API
bankservice Access to the Open Banking API
services.erphub Access to the ERP Hub API

Grant Types

The OpenID Connect and OAuth 2.0 specifications define so-called grant types (often also called flows - or protocol flows). Grant types specify how a client can interact with the token service.

The Control API supports both implicit (user) and client credentials grants. This means that either a ClientID and Client Secret, or a Username and Password can be used to access the API.

Note:

Auhorization Code (PKCE) grant will be added in the future.

Example Request

cURLC#JavaJavaScriptPython
Copy
Copied
curl -i -X POST "https://id.aritma.io/connect/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET"
Copy
Copied
using var client = new HttpClient();

var form = new Dictionary<string, string>
{
    {"grant_type", "client_credentials"},
    {"client_id", "{CLIENT_ID}"},
    {"client_secret", "{CLIENT_SECRET}"},
};
var content = new FormUrlEncodedContent(form);

var response = await client.PostAsync("https://id-dev.zdata.no/connect/token", content);
Copy
Copied
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, 
  "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}");

Request request = new Request.Builder()
  .url("https://id-dev.zdata.no/connect/token")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();

Response response = client.newCall(request).execute();
Copy
Copied
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

var urlencoded = new URLSearchParams();
urlencoded.append("grant_type", "client_credentials");
urlencoded.append("client_id", "{CLIENT_ID}");
urlencoded.append("client_secret", "{CLIENT_SECRET}");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("https://id-dev.zdata.no/connect/token", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
Copy
Copied
import requests

url = "https://id.zdata.no/connect/token"

payload='grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

Postman

In the Postman app, complete the following:

  1. Set the verb to POST .
  2. Enter https://id-dev.zdata.no/connect/token as the request URL.
  3. Select the Body tab.
  4. Select the x-www-form-urlencoded option.
  5. In the KEY field, enter grant_type .
    • In the VALUE field, enter client_credentials .
  6. In the KEY field, enter client_id .
    • In the VALUE field, enter your client id.
  7. In the KEY field, enter client_secret .
    • In the VALUE field, enter your client secret.
  8. Select Send .

Access Token

The token response contains the JWT access token, the number of seconds the token is valid, included scopes and the token type.

Parameter Value
access_token The JWT access token
expires_in The number of seconds the token is valid
token_type The type of the token. Default: Bearer
scope Space-delimited list of scope permissions

When you make calls to a REST API, include the access token in the Authorization header with the designation as Bearer. Reuse the access token until it expires.

Copy
Copied
Authorization: Bearer <token>

Example Response

Copy
Copied
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjRDMzE4NkE5MjUwMjI4MUQ5Njg2NjNCNEQ2MEFDMjI5QUM3MkI3ODJSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IlRER0dxU1VDS0IyV2htTzAxZ3JDS2F4eXQ0SSJ9.eyJuYmYiOjE2NjM1ODg0ODEsImV4cCI6MTY2MzU5MjA4MSwiaXNzIjoiaHR0cHM6Ly9pZC1kZXYuemRhdGEubm8iLCJhdWQiOlsic2VydmljZXMuc2V0dGxlbWVudCIsInphbSIsImh0dHBzOi8vaWQtZGV2LnpkYXRhLm5vL3Jlc291cmNlcyJdLCJjbGllbnRfaWQiOiJTZXR0bGVtZW50RXhhbXBsZUNsaWVudCIsImlhdCI6MTY2MzU4ODQ4MSwic2NvcGUiOlsic2VydmljZXMuc2V0dGxlbWVudCIsInphbSJdfQ.ZPZ0oZ7krdjmnidwlTJegmU2qkFP2QbvLphVfOdCf5lnT6utyLhveTI32RQTrAgmlX4zmpO-Mp5f7Ck3_5L0y1xrmJuvxFDQz3TW8sIdviZzPvFZ86Tt-Yk1dHjgsPaEKygmJGhfktxHGUqslaN_sFZJjyQPkIx5q5HGKnDNBUMo0Vx6TFo1V_HRa56QdGrApuCFjPu7goX6z2Qk0i0y1vVbkpWFqS_z-9m-8TgjF90aTkqWE866TGTZUEHxL10cnJFMQ6KTZk4Ez1tFkWCb9QW3RO8fvSKRDwDjBf0acToKbbyYvxf6XX4FZMRycFiSEsT-0rPPIKXDdB27br7j7g",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "reconcile bankservice services.erphub"
}