Step 2: Implement server side
Learn what you need to configure on your backend to implement the Monite solution.
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.
Try in Postman instead?
If for some reason you are not able to follow the steps below at this moment, you can try the same functionality using our Entities and entity users Postman collection.
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:
curl -X POST 'https://api.sandbox.monite.com/v1/auth/token' \
-H 'X-Monite-Version: 2024-01-31' \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}'
Never store your client secret in plain text. Always treat it in a way you treat any other passwords and API keys in your system, and use a special encrypted storage for this type of sensitive data.
The successful response contains the token and its validity time (in seconds):
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhb...",
"token_type": "Bearer",
"expires_in": 1800
}
You will need this token to authorize your other API calls later in this tutorial.
2. Handle token expiry
A partner token is valid only for 1800 seconds (which is 30 minutes). If you will make a request with an expired token, Monite responds back with a 400 Bad Request error:
{
"error": {
"message": "The token has been expired."
}
}
In 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 a corresponding entity within the Monite platform. Here, you don't need to duplicate all the information you already have about your customers – submit only what's required by Monite. For more information about entities, refer to Monite account structure.
To create an entity, make a POST request to the /entities endpoint. The request's payload represents details of the entity to be created.
curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
-H 'X-Monite-Version: 2024-01-31' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"type" : "organization",
"email": "[email protected]",
"address": {
"city": "Berlin",
"country": "DE",
"line1": "Flughafenstrasse 52",
"postal_code": "10115",
"state": "BE"
},
"organization" : {
"legal_name" : "Dare - Cronin"
}
}'
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.
For this, make a PATCH request to the /entities/{entity_id} endpoint as shown below:
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/e39f87be-d499-411b-be6d-a806c500c139' \
-H 'X-Monite-Version: 2024-01-31' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"organization" : {
"legal_name" : "Dare Cronin Gmbh."
}
}'
The successful response returns an updated object containing all details about the entity.
There are many more things you can and might need to do with entities, however these are not in scope of the current tutorial. For more information, refer to Entities.
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, make a POST request to the /roles endpoint as shown below:
curl -X POST 'https://api.sandbox.monite.com/v1/roles' \
-H 'X-Monite-Version: 2024-01-31' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
{
"name": "Basic role",
"permissions": {
"objects": [
{
"object_type": "entity_user",
"actions": [
{
"action_name": "read",
"permission": "allowed"
},
{
"action_name": "create",
"permission": "allowed"
}
]
},
{
"object_type": "payable",
"actions": [
{
"action_name": "create",
"permission": "allowed"
},
{
"action_name": "read",
"permission": "allowed_for_own"
}
]
},
{
"object_type": "receivable",
"actions": [
{
"action_name": "create",
"permission": "allowed"
},
{
"action_name": "read",
"permission": "allowed_for_own"
}
]
}
]
}
}'
The successful response returns information about the created user role including its unique ID.
6. Create an entity user
To create an entity user, make a POST request to the /entity_users endpoint with the following payload. The role_id field must be populated by the ID of the role created earlier.
curl -X POST 'https://api.sandbox.monite.com/v1/entity_users' \
-H 'X-Monite-Version: 2024-01-31' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"login": "Gardner.Waelchi",
"first_name": "Gardner",
"last_name": "Waelchi",
"role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
"email": "[email protected]",
"phone": "+15551234567",
"title": "Mr."
}'
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.
For this, make a PATCH request to the /entity_users/{entity_id} endpoint as shown below:
curl -X PATCH 'https://api.sandbox.monite.com/v1/entity_users/da2a21c7-ed54-4b1e-a8b8-8048588328f5' \
-H 'X-Monite-Version: 2024-01-31' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"first_name": "TestName"
}'
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 grant_type set to entity_user, and specify the ID of this user in the entity_user_id request field:
curl -X POST 'https://api.sandbox.monite.com/v1/auth/token' \
-H 'X-Monite-Version: 2024-01-31' \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "entity_user",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
"entity_user_id": "e7525084....fd94153226fb781"
}'
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:
Updated 5 months ago