How to use Mint API

Getting started

MintHCM API version 8 exposes a set of resources, to be consumed by clients who wish to harness the powerful HCM functionality provided by MintHCM. As such MintHCM is based on SuiteCRM, so the API is very similar. Hoever there are differences.

The API framework employs a Restful design to facilitate the JSON API 1.0 standard messages over HTTPS. It includes metaobjects to provide functionality which is not yet defined in the JSON API 1.0 standard. The MintHCM API is secured by the OAuth 2 Server provided in MintHCM.

Requirements

In order to prevent man-in-the-middle attacks, the authorization server MUST require the use of TLS with server authentication as defined by RFC2818 for any request sent to the authorization and token endpoints.

The client MUST validate the authorization server’s TLS certificate as defined by RFC6125 and in accordance with its requirements for server identity authentication.

MintHCM uses key cryptography in order to encrypt and decrypt, as well as verify the integrity of signatures.

Please ensure that you have the following:

OpenSSL Extension installed and configured
The MintHCM instance must be configured to use HTTPS/SSL
You need to have PHP version 5.5.9 or 7.0 and above

Before you start, please check that everything is properly connected.

JSON API

Before you start calling endpoints

Please check the following below:

Composer

Install composer packages with

composer install

Generate private and public.key for OAUTH2

MintHCM API uses OAuth2 protocol, which needs public and private keys.

First, open a terminal and go to:

composer install

Generate a private key:

openssl genrsa -out private.key 2048

Then a public key:

openssl rsa -in private.key -pubout -out public.key

If you require more information, you can check this page.

The permission of the key files must be 600 or 660, so change it.

sudo chmod 600 private.key public.key

Also, you have to be sure that the config files are owned by PHP.

sudo chown www-data:www-data p*.key

OAUTH2 encryption key

OAuth2’s AuthorizationServer needs to set an encryption key for security reasons. This key has been generated during the MintHCM installation and stored in the config.php under “oauth2_encryption_key”. If you would like to change its value, you may generate a new one by running

php -r ‘echo base64_encode(random_bytes(32)), PHP_EOL;’

and then store the output in the config.php

Current releases all use the value directly from config.php

Older versions updated the file legacy/Api/Core/Config/Apiconfig.php with the value from config.php when running a repair and rebuild. If any issues arise, and you are troubleshooting it may be worth taking a look there.

If you require any more info, you can check this page.

Verify if rewrite module is installed and activated

It is necessary to verify if ‘mod_rewrite’ module of Apache server is enabled. Make sure to enable and activate it. This process depends on Operating System, installed versions of software etc. Please check this stackoverflow’s answers 1, 2 to get directions how to enable the module.

Also, for the MintHCM location (root{/var/www} or subdir{/var/www/subdir}) one should change AllowOverride directive inside Directory directive from None to All to assure that rewrite rules of .htaccess work:

Options Indexes FollowSymLinks

AllowOverride All

Require all granted

</Directory>

Authentication

MintHCM Api allows two kind of grant types:

Client credential
Password

Parameter	Description
Access Token URL	{{minthcm.url}}/Api/access_token
Username	Only available for Password grants. Must be a valid MintHCM user name.
Password	Only available for Password grants. Password for the selected user.
Client ID	Client ID exists in OAuth2Clients module’s ID. Must be a valid GUID.
Client Secret	Client secret is also in OAuth2Clients module as SHA256 generated value.
Scopes	Scopes haven’t implemented yet

Available parameters

According to JsonApi specification, the available parameters are the following depending on the GET endpoint:

Fields

Fields can filter on attribute object. Allowed keys are valid bean properties.

Example:

{{minthcm.url}}/Api/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493?fields[Accounts]=name,account_type

Result:

{

“data”: {

“type”: “Account”,

“id”: “11a71596-83e7-624d-c792-5ab9006dd493”,

“attributes”: {

“name”: “White Cross Co”,

“account_type”: “Customer”

“relationships”: {

“AOS_Contracts”: {

“links”: {

“related”: “/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493/relationships/aos_contracts”

}

Sort

Sort is only available when collections wanted to be fetched. Sorting is set to ASC by default. If the property is prefixed with hyphen, the sort order changes to DESC.

Important notice: we only support single sorting right now!

Example:

{{minthcm.url}}/Api/V8/module/Accounts?sort=-name

Result:

{

“data”: [

{

“type”: “Account”,

“id”: “e6e0af95-4772-5773-ae70-5ae70f931feb”,

“attributes”: {

“name”: “White Cross Co”,

“account_type”: “Customer”

“relationships”: {

“AOS_Contracts”: {

“links”: {

“related”: “/V8/module/Accounts/1d125d2a-ac5a-3666-f771-5ab9008b606c/relationships/aos_contracts”

}

{

“type”: “Account”,

“id”: “7831d361-2f3c-dee4-d36c-5ab900860cfb”,

“attributes”: {

“name”: “Union Bank”,

“account_type”: “Customer”

“relationships”: {

“AOS_Contracts”: {

“links”: {

“related”: “/V8/module/Accounts/7831d361-2f3c-dee4-d36c-5ab900860cfb/relationships/aos_contracts”

}

Filter

Our filter strategy is the following:

Filter[operator]=and
Filter[account_type][eq]=Customer

Important notice: we don’t support multiple level sorting right now!

Supported operators

Comparison

EQ = ‘=’;

NEQ = ‘<>’;

GT = ‘>’;

GTE = ‘>=’;

LT = ‘<‘;

LTE = ‘<=’;

Logical

‘AND’, ‘OR’

Example:

{{minthcm.url}}/Api/V8/module/Accounts?fields[Accounts]=name,account_type&filter[operator]=and&filter[account_type][eq]=Customer

Example:

{{minthcm.url}}/Api/V8/module/Accounts?filter[account_type][eq]=Customer

Result:

Endpoints

Logout

POST {{mintHCM.url}}/Api/V8/logout

Modules

GET {{mintHCM.url}}/Api/V8/meta/modules

Module Fields

GET {{mintHCM.url}}/Api/V8/meta/fields/{moduleName}

Get a module by ID

GET {{mintHCM.url}}/Api/V8/module/{moduleName}/{id}

Available parameters: fields

Example:

Api/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493?fields[Accounts]=name,account_type

Get collection of modules

GET {{mintHCM.url}}/Api/V8/module/{moduleName}

Available parameters: fields, page, sort, filter

Example:

Api/V8/module/Accounts?fields[Accounts]=name,account_type&page[size]=4&page[number]=4

Create a module record

POST {{mintHCM.url}}/Api/V8/module

Example body:

{

“data”: {

“type”: “Accounts”,

“attributes”: {

“name”: “Test account”

}

Update a module record

PATCH {{minthcm.url}}/Api/V8/module

Example body:

{

“data”: {

“type”: “Accounts”,

“id”: “11a71596-83e7-624d-c792-5ab9006dd493”,

“attributes”: {

“name”: “Updated name”

}

Delete a module record

DELETE {{minthcm.url}}/Api/V8/module/{moduleName}/{id}

Get relationship

GET {{minthcm.url}}/Api/V8/module/{moduleName}/{id}/relationships/{relatedModuleName}

Example:

Api/V8/module/Accounts/129a096c-5983-1d59-5ddf-5d95ec91c144/relationships/Accounts

Create relationship

POST {{minthcm.url}}/Api/V8/module/{moduleName}/{id}/relationships

Example body:

{

“data”: {

“type”: “Contacts”,

“id”: “129a096c-5983-1d59-5ddf-5d95ec91c144”

}

Delete relationship

DELETE {{minthcm.url}}/Api/V8/module/{moduleName}/{id}/relationships/{relatedModule}/{relatedBeanId}

Example:

/Api/V8/module/Accounts/129a096c-5983-1d59-5ddf-5d95ec91c144/relationships/Accounts/11a71596-83e7-624d-c792-5ab9006dd493

Configure Authentication: Obtaining A Session

The MintHCM API requires that a client has an active session to consume the API. Sessions are acquired by authenticating with the OAuth 2 Server, using one of the available grant types.

Configure Grant Types

Before you can consume the API, you must first configure MintHCM to grant access to a client. MintHCM 4.1 provides an administrative panel, through which you can add clients and revoke tokens. To configure the grant types, select the admin panel, and then select OAuth2 Clients and Tokens:

Client Credentials Grant

A client credentials grant is the simplest of all of the grants types, this grant is used to authenticate a machine or service. Select new client credentials client:

Begin configuring the grant:

Field	Description
Name	This makes it easy to identify the client.
Secret	Defines the client_secret which is posted to the server during authentication.
Is Confidential	A confidential client is an application thet is capable of keeping a client password confidentional to the world.
Associated User	Limits the clients access to CRM, by associating the client with the security privileges of a user.

The ‘secret’ will be hashed when saved, and will not be accessible later. The ‘id’ is created by MintHCM and will be visible once the client is saved.

Authentication with Client Credentials

POST /Api/access_token

Required parameters

Param	Value
grant_type	client_credentials
client_id	ExampleClientName
Client_secret	ExampleSecretPassword

Exampe Request (PHP):

$ch = curl_init();

$header = array(

‘Content-type: application/vnd.api+json’,

‘Accept: application/vnd.api+json’,

);

$postStr = json_encode(array(

‘grant_type’ => ‘client_credentials’,

‘client_id’ => ‘3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650’,

‘client_secret’ => ‘client_secret’,

));

$url = ‘https://path-to-instance/Api/access_token’;

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ‘POST’);

curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_HTTPHEADER, $header);

$output = curl_exec($ch);

Example Response:

{

“token_type”:”Bearer”,

“expires_in”:3600,

“access_token”:”eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjdkOTEyODNhMjc1NDdkNDRlMzNmOTc5ZjVmMGRkYzQwNzg1ZGY5NGFhMWI5MDVlZGNmMzg3NWIxYjJkZDMzNDljZWEyNjZhMTQ2OTE5OWIzIn0.eyJhdWQiOiJzdWl0ZWNybV9jbGllbnQiLCJqdGkiOiI3ZDkxMjgzYTI3NTQ3ZDQ0ZTMzZjk3OWY1ZjBkZGM0MDc4NWRmOTRhYTFiOTA1ZWRjZjM4NzViMWIyZGQzMzQ5Y2VhMjY2YTE0NjkxOTliMyIsImlhdCI6MTUxODE5NTEwMiwibmJmIjoxNTE4MTk1MTAyLCJleHAiOjE1MTgxOTg3MDIsInN1YiI6IjEiLCJzY29wZXMiOltdfQ.EVGuRisoMxSIZut3IWtgOYISw8lEFSZgCWYCwseLEfOuPJ8lRMYL4OZxhu9gxJoGF0nj3yc6SYDPxovrsoj8bMoX38h4krMMOHFQLoizU0k2wAceOjZG1tWKPhID7KPT4TwoCXbb7MqAsYtVPExH4li7gSphJ8wvcWbFdS5em89Ndtwqq3faFtIq6bv1R4t0x98HHuT7sweHUJU40K9WQjbAfIOk8f5Y6T2wassN2wMCBB8CC6eUxLi14n2D6khHvkYvtPbXLHpXSHZWvEhqhvjAeSR5MmMrAth9WDSWUx7alO-ppsZpi8U7-g9Be5p6MRatc25voyTI2iTYbx02FQ”,

}

token_type	The Bearer token value
expires_in	an integer representing the TTL of the access token
access_token	a JWT signed with the authorization server’s private key. It is required that you include this in the HTTP headers, each time you make a request to the API

Example:

$header = array(

‘Content-type: application/vnd.api+json’,

‘Accept: application/vnd.api+json’,

‘Authorization: Bearer ‘ . $your_saved_access_token

);

Password Grant

A password grant is used for allow users to log into MintHCM with a username and a password. Select new password client:

Begin configuring grant:

Name	This makes it easy to identify the client.
Secret	Defines the client_secret which is posted to the server during authentication.
Is Confidential	A confidential client i san application that is capable of keeping a client password confidential to the world.

The ‘secret’ will be hashed when saved, and will not be accessible later. The ‘id’ is created by MintHCM and will be visible once the client is saved.

Authentication with Password Grant

POST /Api/access_token

Required parameters

Param	Value
grant_type	Password
client_id	ExampleClientName
client_secret	ExampleSecretPassword
Username	Admin
Password	secret

Please change the values in bold to match your chosen authentication details.

Example Request (PHP):

$ch = curl_init();

$header = array(

‘Content-type: application/vnd.api+json’,

‘Accept: application/vnd.api+json’,

);

$postStr = json_encode(array(

‘grant_type’ => ‘password’,

‘client_id’ => ‘3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650’,

‘client_secret’ => ‘client_secret’,

‘username’ => ‘admin’,

‘password’ => ‘admin’,

));

$url = ‘https://path-to-instance/Api/access_token’;

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ‘POST’);

curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_HTTPHEADER, $header);

$output = curl_exec($ch);

Example Response:

{

“token_type”:”Bearer”,

“expires_in”:3600,

“refresh_token”:”def50200d2fb757e4c01c333e96c827712dfd8f3e2c797db3e4e42734c8b4e7cba88a2dd8a9ce607358d634a51cadd7fa980d5acd692ab2c7a7da1d7a7f8246b22faf151dc11a758f9d8ea0b9aa3553f3cfd3751a927399ab964f219d086d36151d0f39c93aef4a846287e8467acea3dfde0bd2ac055ea7825dfb75aa5b8a084752de6d3976438631c3e539156a26bc10d0b7f057c092fce354bb10ff7ac2ab5fe6fd7af3ec7fa2599ec0f1e581837a6ca2441a80c01d997dac298e1f74573ac900dd4547d7a2a2807e9fb25438486c38f25be55d19cb8d72634d77c0a8dfaec80901c01745579d0f3822c717df21403440473c86277dc5590ce18acdb1222c1b95b516f3554c8b59255446bc15b457fdc17d5dcc0f06f7b2252581c810ca72b51618f820dbb2f414ea147add2658f8fbd5df20820843f98c22252dcffe127e6adb4a4cbe89ab0340f7ebe8d8177ef382569e2aa4a54d434adb797c5337bfdfffe27bd8d5cf4714054d4aef2372472ebb4″

}

token_type	The Bearer token value
espires_in	an integer representing the TTL of the access token
access_token	a JWT signed with the authorization server’s private key. It is required that you include this in the HTTP headers, each time you make a request to the API
refresh_token	an encrypted payload that can be used to refresh the access token when it expires.

You can store the bearer token in a database and use in your requests like this:

Example:

$header = array(

‘Content-type: application/vnd.api+json’,

‘Accept: application/vnd.api+json’,

‘Authorization: Bearer ‘ . $your_saved_access_token

);

Refresh Token Grant

A refresh token grant is used if you already have a refresh token generated from password grant. It is used to get a new access token.

“grant_type”: “refresh_token”,

“client_id”: “Client Id”,

“client_secret”: “Client Secret”,

“refresh_token”: “refresh token” (returned with password grant)

Getting Access Token using Refresh Grant

POST /Api/access_token

Required parameters

Param	Value
grant_type	refresh_token
client_id	Client ID
client_secret	Client Secret
refresh_token	Refresh token

Please change the values in bold to match your chosen authentication details.

Example Request (PHP):

$ch = curl_init();

$header = array(

‘Content-type: application/vnd.api+json’,

‘Accept: application/vnd.api+json’,

);

$postStr = json_encode(array(

‘grant_type’ => ‘refresh_token’,

‘client_id’ => ‘3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650’,

‘client_secret’ => ‘client_secret’,

‘refresh_token’ => ‘refresh_token’,

));

$url = ‘https://path-to-instance/Api/access_token’;

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ‘POST’);

curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_HTTPHEADER, $header);

$output = curl_exec($ch);

Example Response:

{

“token_type”:”Bearer”,

“expires_in”:3600,

}

token_type	The Bearer token value
expires_in	an integer representing the TTL of the access token
access_token	a JWT signed with the authorization server’s private key. It is required that you include this in the HTTP headers, each time you make a request to the API
refresh_token	an encrypted payload that can be used to refresh the access token when it expires.

Getting Awailable Resources

Swagger Documentation

To see what resources and authentication methods are available, you can retrieve the swagger documentation via 2 routes

On the server the documentation is located at

{{minthcm.url}}/legacy/Api/docs/swagger/swagger.json

You can also retrieve the documentation via an API call:

GET {{minthcm.url}}/Api/V8/meta/swagger.json

The swagger documentation is a JSON file that includes information on what the default API is capable of and how to structure an API call.

An example of one of the paths included is shown below.

“paths”: {

“/module/{moduleName}/{id}”: {

“get”: {

“tags”: [

“Module”

“description”: “Returns a bean with the specific ID”,

“parameters”: [

{

“name”: “moduleName”,

“in”: “path”,

“description”: “Name of the module”,

“required”: true,

“schema”: {

“type”: “string”

“example”: “Contacts”

{

“name”: “id”,

“in”: “path”,

“description”: “ID of the module”,

“required”: true,

“schema”: {

“type”: “string”,

“format”: “uuid”

“example”: “b13a39f8-1c24-c5d0-ba0d-5ab123d6e899”

{

“name”: “fields[Contacts]”,

“in”: “query”,

“description”: “Filtering attributes of the bean”,

“schema”: {

“type”: “string”

“example”: “name,account_type”

}

“responses”: {

“200”: {

“description”: “OK”

“400”: {

“description”: “BAD REQUEST”

}

“security”: [

{

“oauth2”: []

}

]

}

This will tell you everything you need to know about how to structure the API Request. A description of the array can be found below.

path

The path or URI of this api request i.e.

“{{minthcm.url}}/module/{moduleName}/{id}”

get

The type of request e.g. GET/POST/PATCH

description

Lets you know what this request is for.

parameters

Lets you know what can be included in the request.

“name” is the name of the parameter or what it replaces in the path.
„in” lets you know where this parameter should go
„path” means it replaces one of the varaiables in curly braces in the path
„query”means it should be included in the body of the API call to be successful
„required” lets you know if this parameter must be included for the API call to be successful
„schema” describes the type/format of the parameter
„example” provides an example of how the parameter is used in the API call.

responses

The http messages to expect with the API Response.

security

The erquired security for the API call.

MintHCM V8 API Set Up For Postman

Steps to Set Up V8 API on Postman

Composer

Install composer packages with

composer install

.htaccess rebuild

Go to Admin Panel → Repair → Rebuild .htaccess File

Import Collection File into Postman

1 – Click Import

2 – Import collection file. You can find it in Api/docs/postman

Note: If you can’t find your collection file it may been in a directory that postman can’t upload from – Solution: Move collection file into documents.

Setup Environment

1 – Click Manage Environments → Add

2 – Set Environment name – Example: MintHCM V8 API Environment

3 – Fill table out as shown below:

variable	Initial value	Current value
Minthcm.url	http://{{IP ADDRESS}}/{{Your Instance}}/Api	http://{{IP ADDRESS}}/{{Your Instance}}/Api
Token.url	http://{{IP ADDRESS}}/{{Your Instance}}/Api/access_token	http://{{IP ADDRESS}}/{{Your Instance}}/Api/access_token

→ Add

4 – Click Environment from the Drop down

Managing Tokens

The OAuth 2 admin panel displays which session have been successfully created.

You can also revoke or end an active session by selected the session and then selecting “revoke token” in the action or bulk actions menu.

Customization

Each customization should be in a base folder

custom/Extension/application/Ext/Api/V8/

See more about Slim framework at https://www.slimframework.com/.

Extending Slim configuration in custom/application/Ext/Api/V8/slim.php is a native php file should returns an array of slim configurations. Additional configuration will be merged into the default slim configuration.

return [ /* slim configuration here …*/ ];

Extending Routes in custom/application/Ext/Api/V8/Config/routes.php is a native php file given $app variable as a Slim application. Additional routes will be added into the default slim application and available in URL [MintHCM-path]/Api/V8/custom custom/application/Ext/Api/V8/Config/routes.php

$app->post(‘/my-route/{myParam}’, ‘MyCustomController:myCustomAction’);

Extending Services in custom/application/Ext/Api/V8/services.php is a native php file should returns an array of slim services. Additional services will be merged into the default slim services. custom/application/Ext/Api/V8/services.php

return [‘myCustomService’ => function() {

return new MyCustomService();

}];

Extending BeanAliases in custom/application/Ext/Api/V8/beanAliases.php is a native php file should returns an array of custom bean aliases. custom/application/Ext/Api/V8/beanAliases.php

return [MyCustom::class => ‘MyCustoms’];

Extending Controllers in custom/application/Ext/Api/V8/controllers.php is a native php file should returns an array of custom controllers. custom/application/Ext/Api/V8/controllers.php

return [MyCustomController::class => function(Container $container) {

return new MyCustomController();

}];

Extending Factories in custom/application/Ext/Api/V8/factories.php is a native php file should returns an array of custom factories. custom/application/Ext/Api/V8/factories.php

return [MyCustomFactory::class => function(Container $container) {

return new MyCustomFactory();

}];

Extending Globals in custom/application/Ext/Api/V8/globals.php is a native php file should returns an array of custom globals. custom/application/Ext/Api/V8/globals.php

return [MyCustomGlobal::class => function(Container $container) {

return new MyCustomFactory();

}];

Extending Helpers in custom/application/Ext/Api/V8/helpers.php is a native php file should returns an array of custom helpers. custom/application/Ext/Api/V8/helpers.php

return [MyCustomHelper::class => function(Container $container) {

return new MyCustomHelper();

}];

Extending Middlewares in custom/application/Ext/Api/V8/middlewares.php is a native php file should returns an array of custom middlewares. custom/application/Ext/Api/V8/middlewares.php

return [MyCustomMiddleware::class => function(Container $container) {

return new MyCustomMiddleware();

}];

Extending Params in custom/application/Ext/Api/V8/params.php is a native php file should returns an array of custom params. custom/application/Ext/Api/V8/params.php

return [MyCustomParam::class => function(Container $container) {

return new MyCustomParam();

}];

Extending Validators in custom/application/Ext/Api/V8/validators.php is a native php file should returns an array of custom validators. custom/application/Ext/Api/V8/validators.php

return [MyCustomValidator::class => function(Container $container) {

return new MyCustomValidator();

}];

Basic example of API customization

Create a file for new custom route: [MintHCM-path]/custom/application/Ext/Api/V8/Config/routes.php with the following content:

<?php

$app->get(‘/hello’, function() {

return ‘Hello World!’;

});

How to use Mint API

Getting started

Requirements

JSON API

Before you start calling endpoints

Composer

Generate private and public.key for OAUTH2

OAUTH2 encryption key

Verify if rewrite module is installed and activated

Authentication

Available parameters

Fields

Page

Sort

Filter

Supported operators

Comparison

Logical

Endpoints

Logout

Modules

Module Fields

Get a module by ID

Get collection of modules

Create a module record

Update a module record

Delete a module record

Get relationship

Create relationship

Delete relationship

Configure Authentication: Obtaining A Session

Configure Grant Types

Client Credentials Grant

Authentication with Client Credentials

Required parameters

Password Grant

Authentication with Password Grant

Required parameters

Refresh Token Grant

Getting Access Token using Refresh Grant

Required parameters

Getting Awailable Resources

Swagger Documentation

path

get

description

parameters

responses

security

MintHCM V8 API Set Up For Postman

Steps to Set Up V8 API on Postman

Composer

.htaccess rebuild

Import Collection File into Postman

Setup Environment

Managing Tokens

Customization

Basic example of API customization