...

In order for a Third Party System to access CRM.COM, authentication must be acquired before performing any logical unit of work.

This can be accomplished by using one of the two three methods;

• Web API Keys

...

• Consumer Application Keys
• Username & Password.

Regardless of the method used, a JWT authentication token is retrieved which can subsequently be used by all other Web API methods to access the system.

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact stateless and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret key (with the HMAC algorithm) or a public/private key pair using RSA. 

JSON Web Tokens in CRM.COM should have length more than 32 characters and they consist of three parts separated by dots (.), which are:

• Header
  • typ: The type of the token, which is JWT
  • alg: The hashing algorithm being used, which is HS256
• Payload: contains the claims which are statements about an the user and additional metadata.
  • jti: The ID of the user session as generated by CRM.COM
  • usr: The username of the logged in user
  • org: The organisation name of the organisation that the user logged in
  • oun: The unit name of the unit that the user logged in
  • exp: The expiration time on or after which the JWT becomes invalid and should not be accepted for processing. 
  • iat: The time at which the JWT was issued
  • cii: The contact information identifier (applicable only when authenticating consumer-based applications)

  • acr: The accounts receivable identifier (applicable only when authenticating consumer-based applications)

• Signature: is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way. The signature is created by encoding the header and payload and signing them using a secret and the HS256 algorithm

...

Note that the JWT values are case sensitive. Also the exp and iat claims are defined in as numeric dates. A numeric date is a JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. There are online tools that you can use to check and validate the JWT, such as the JWT Debugger and also to calculate and validate numeric dates, such as the Epoch Converter

...

This is the recommended method of authentication using Web API Keys of a "Systemic Key" classification. Web API Keys are assigned to specific users in order to access a specific organisation and can be used to authenticate users through Web API, resulting to an authentication token that can subsequently be used by other Web API calls. 

Once a User is created, (more information can be found at Managing Users) then a Web API Key can be created and assigned to a user. In order for the user to be authenticated the POST authentication/web_api_key/token method must be used. It is based on HTTP Basic Auth and requires a Web API Key. 

...

 {
  	"data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c3IiOiJNUEFkbWluaXN0cmF0b3IiLCJvcmciOiJwc19yMTNxYSIsIm91biI6IjEiLCJleHAiOiIxNDk1NzIwNTgyIiwiaWF0IjoiMTQ5NTcxMzM4MiIsImp0aSI6IkM5NzI5NDlFOEZGMTRFMjI5RjU4MjkxQUJFM0MyNjYzIn0.6-9y-NTFoxjYDcnZb_Z6gVgFwPdvV82nIpuGTQ3v0wQ"
	},
	"status": {
    	"code": "OK",
	    "description": "",
	    "message": ""
	}
}

How to Authenticate with Consumer Application Key Method

This is an alternative method of authentication using Web API Keys of a "Consumer Application Key" classification. Web API Keys are assigned to specific users in order to access a specific organisation and can be used to authenticate users through Web API, resulting to an authentication token that can subsequently be used by other Web API calls

Once a User is created, (more information can be found at Managing Users) then a Web API Key can be created and assigned to a user. In order for the user to be authenticated the POST authentication/consumer_application_key/token method must be used. It is based on HTTP Basic Auth and requires a Web API Key along with a Consumer Access Token

{{server}}/crmapi/rest/v2/authentication/consumer_application_key/token

Content-Type: application/json
Authorization: The encrypted Web API Key which set as the authorisation parameter based on the HTTP Basic Authorisation protocol

{
    "access_token_identifier": {
		"authentication_code": "authentication_code"
	},
    "unit":"unit"
}
Note that the unit parameter is optional. If not specified then the default unit of the user that is represented by the specified Web API key will be used

{
	"data": {
		"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjaWkiOiIyNjk1RkVEM0ZDRkQ0MDg0QUIzOUY0NEIxODg4OTEyMyIsInVzciI6Im1heXRlbXBsYXRlIiwib3JnIjoicHNfZGV2IiwiYXJpIjoiMjYxQkYyQjc5MTk4NDAxRDg5QTc5QzU0NUYxNkNCRUMiLCJvdW4iOiIxIiwiZXhwIjoiMTUxODEwNDg2NCIsImlhdCI6IjE1MTgwOTc2NjQiLCJqdGkiOiJGNTg2QjI4ODA0OEE0MTAwQjc0OUU2MkY0N0RGQzg0NCJ9.yvRGqFy7dL2H6RcqXOJQtD3zBoWHUDpoRN9Ma6hKfpg"
	},
	"status": {
    	"code": "OK",
	    "description": "",
	    "message": ""
  	}
}

How to Authenticate with Username & Password Method

...

{
    "username": "username",
    "password": "1234",
    "organisation": "organisation",
    "unit": "unit"
}
 
Note that the unit parameter is optional. If not specified then the default unit of the user will be used

 {
  	"data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c3IiOiJNUEFkbWluaXN0cmF0b3IiLCJvcmciOiJwc19yMTNxYSIsIm91biI6IjEiLCJleHAiOiIxNDk1NzIwNTgyIiwiaWF0IjoiMTQ5NTcxMzM4MiIsImp0aSI6IkM5NzI5NDlFOEZGMTRFMjI5RjU4MjkxQUJFM0MyNjYzIn0.6-9y-NTFoxjYDcnZb_Z6gVgFwPdvV82nIpuGTQ3v0wQ"
  	},
  	"status": {
    	"code": "OK",
	    "description": "",
	    "message": ""
  	}
}

How to Refresh Authentication Token

Based on the parameters passed to JWT authorisation, through the payload section, the "exp" parameter sets the expiration time on or after which the JWT becomes invalid and should not be accepted for processing. 

CRM.COM sets the expiration time to be 2 hours after the authentication token is used. Once the authentication token becomes expired then users must refresh by executing one of the above methods to acquire a new authentication token.