Step 2: Implement server side

Overview

No matter what integration type you will choose for your Client-side implementation, there are some certain steps that can be only implemented on your backend. Please note that this tutorial shows code snippets for each step in JSON, while the exact implementation depends on the programming language and framework you use for your server side.

Before you begin

Before proceeding with this tutorial, make sure you completed the steps in the Step 1: Get your credentials guide and are able to generate a partner access token.

1. Generate a partner access token

All API calls coming from your backend should be authenticated with a token of grant_type: client_credentials, which is called a “partner access token”. You already learned how to generate this token in the previous tutorial, and now you need to create a token generation function on your backend that will do the following:

1
curl -X POST 'https://api.sandbox.monite.com/v1/auth/token' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Content-Type: application/json' \
4
     -d '{
5
        "grant_type": "client_credentials",
6
        "client_id": "YOUR_CLIENT_ID",
7
        "client_secret": "YOUR_CLIENT_SECRET"
8
     }'

The successful response contains the token and its validity time (in seconds):

1
{
2
  "access_token": "eyJ0eXAiOiJKV1QiLCJhb...",
3
  "token_type": "Bearer",
4
  "expires_in": 1800
5
}

You will need this token to authorize your other API calls later in this tutorial.

2. Handle token expiration

A partner token is valid only for 1800 seconds (30 minutes). If you will make a request with an expired token, Monite responds back with a 400 Bad Request error:

1
{
2
  "error": {
3
    "message": "The token has been expired."
4
  }
5
}

On your server-side code, implement a mechanism to handle this error and generate a new token, in the same way as you did in the previous step.

3. Create an entity

For each customer you have in your product, you need to create the corresponding entity in Monite. Here, you do not need to duplicate all the information you already have about your customers – submit only what is required by Monite. For more information about entities, refer to Monite account structure.

To create an entity, call POST /entities and provide the entity details:

1
curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Content-Type: application/json' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
    "type" : "organization",
8
    "email": "info@example.com",
9
    "address": {
10
        "city": "Berlin",
11
        "country": "DE",
12
        "line1": "Flughafenstrasse 52",
13
        "postal_code": "10115",
14
        "state": "BE"
15
    },
16
    "organization" : {
17
        "legal_name" : "Dare - Cronin"
18
    }
19
}'

The successful response returns information about the created entity including its unique ID.

4. Update an entity

It is important that you keep this customer information in sync with what you store as an entity on the Monite side. Therefore, in your server-side code, implement a function to update an existing entity, when needed.

To do this, send a PATCH request to the /entities/{entity_id} endpoint as shown below:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/e39f87be-d499-411b-be6d-a806c500c139' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Content-Type: application/json' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -d '{
6
       "organization" : {
7
         "legal_name" : "Dare Cronin Gmbh."
8
       }
9
     }'

The successful response returns an updated object containing all details about the entity.

5. Create an entity user role

Each entity can have one or more users enabled to perform various operations on the Monite platform. Before creating them, you need to define one or more roles and permissions associated with these roles. For more details on the RBAC system used at Monite and some real-life examples of entity user roles, refer to Monite account structure.

To create a role, call POST /roles and specify the role name and permissions:

1
curl -X POST 'https://api.sandbox.monite.com/v1/roles' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '
7
     {
8
      "name": "Basic role",
9
      "permissions": {
10
        "objects": [
11
          {
12
            "object_type": "entity_user",
13
            "actions": [
14
              {
15
                "action_name": "read",
16
                "permission": "allowed"
17
              },
18
              {
19
                "action_name": "create",
20
                "permission": "allowed"
21
              }
22
            ]
23
          },
24
          {
25
            "object_type": "payable",
26
            "actions": [
27
              {
28
                "action_name": "create",
29
                "permission": "allowed"
30
              },
31
              {
32
                "action_name": "read",
33
                "permission": "allowed_for_own"
34
              }
35
            ]
36
          },
37
          {
38
            "object_type": "receivable",
39
            "actions": [
40
              {
41
                "action_name": "create",
42
                "permission": "allowed"
43
              },
44
              {
45
                "action_name": "read",
46
                "permission": "allowed_for_own"
47
              }
48
            ]
49
          }
50
        ]
51
      }
52
    }'

The successful response returns information about the created user role including its unique ID.

6. Create an entity user

To create an entity user, call POST /entity_users with the following request body. The role_id field must be populated with the ID of the role created earlier:

1
curl -X POST 'https://api.sandbox.monite.com/v1/entity_users' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "login": "Gardner.Waelchi",
8
       "first_name": "Gardner",
9
       "last_name": "Waelchi",
10
       "role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
11
       "email": "g.waelchi@example.com",
12
       "phone": "+15551234567",
13
       "title": "Mr."
14
     }'

The successful request returns information about the created entity user.

7. Update an entity user

Similar to entities, you need to make sure that entity user information is always in sync with what you store on the Monite side. Therefore, in your server-side code, implement a function to update an existing entity user, when needed.

To do this, send a PATCH request to the /entity_users/{entity_id} endpoint as shown below:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/entity_users/da2a21c7-ed54-4b1e-a8b8-8048588328f5' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Content-Type: application/json' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json'
6
     -d '{
7
       "first_name": "TestName"
8
     }'

The successful response returns an updated object containing all details about the entity user.

8. Generate an entity-user token

Every time an entity user logs into you application, you also need to issue an individual token for this entity user on the Monite platform. This token will be required for you in the next step, when implementing the client-side integration.

To generate an entity user token, call POST /auth/token with the grant_type set to entity_user, and specify the ID of this user in the entity_user_id request field:

1
curl -X POST 'https://api.sandbox.monite.com/v1/auth/token' \
2
     -H 'X-Monite-Version: 2023-09-01' \
3
     -H 'Content-Type: application/json' \
4
     -d '{
5
        "grant_type": "entity_user",
6
        "client_id": "YOUR_CLIENT_ID",
7
        "client_secret": "YOUR_CLIENT_SECRET"
8
        "entity_user_id": "e7525084....fd94153226fb781"
9
     }'

A successful 200 OK response contains the entity user-level access_token and its validity time (in seconds).

Next steps

You have now built all the required components of your server-side implementation. Next, you need to choose with client-side components you need to use to embed AP and AR products into your application:

• Step 3: Implement client side