Authentication

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 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 a 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 is used, which is HS256
Payload: contains the claims which are statements about 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 organization name of the organization 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 using Consumer Application Keys)
- acr: The accounts receivable identifier (applicable only when authenticating using Consumer Application Keys)
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

The final JWT is created by concatenating the encoded header, encoded payload and encoded signature as follows

encoded header + '.' + encoded payload + '.' + encoded signature

Note that the JWT values are case sensitive. Also, exp and iat claims are defined 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 calculate and validate numeric dates, such as the Epoch Converter

How to Authenticate with Web API Key Method

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 organization 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

Authenticating using this method does not restrict data retrieval that is owned by only one Accounts Receivable

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

Request

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

Headers

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

Body

{
    "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

Response

{
	"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 organization 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

Authenticating using this method provides the ability to retrieve data that are owned only by the Accounts Receivable that is identified through the specified Access Token

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 an Access Token that is related to a Customer

Request

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

Headers

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

Body

{
    "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

Response

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

Consumer Application Web API Methods Exceptional Behavior

Authenticating using this method provides the ability to retrieve data that are owned only by the Accounts Receivable that is identified through the specified Access Token, as a result some Web API Methods that require or retrive another customer infomration (Accounts Receivable/Contact Information) will not work properly

Below is a list of all affected Web API Methods and their exceptional behavior that differs from the expected one

Web API Method	Behavior
contact_information/list contact_information/show contact_information/update contact_information/change_kyc_profile contact_information/verify_kyc_profile contact_information/refute_kyc_profile	In general, Contact Information methods that retrieve another Contact Information as part of their Relations will not be restricted and such information will be retrieved
contact_information/create	Creating a new Contact Information cannot be performed as the authenticated contact identifier (encapsulated in the JSON Web Token Payload) will be different than the newly created contact identifier
accounts_receivable/bill	This method normally bills an Accounts Receivable and all funded services of the Accounts' Member (if the Account is parent to a group). Due to the fact that the consumer-based key is authenticated using the parent account, the system will not allow retrieving data that are not related with the parent account (specifically the subscription of the member)
accounts_receivable/add_member	This method normally adds a member to a specific Account Group. Due to the fact that the consumer-based key is authenticated using the parent account, the system will not allow retrieving another Accounts Receivable after performing such action, as a result this method will never return the parent account's members
accounts_receivable/remove_member	This method normally removes a member to a specific Account Group. Due to the fact that the consumer-based key is authenticated using the parent account, the system will not allow retrieving another Accounts Receivable after performing such action, as a result this method will never return the remaining parent account's members
accounts_receivable/group_members/list	This method normally returns the members of a specific Account Group. Due to the fact that the consumer-based key is authenticated using the parent account, the system will not allow retrieving another Accounts Receivable after performing such action, as a result this method will never return the parent account's members
accounts_receivable/create	Creating a new Accounts Receivable cannot be performed as the authenticated account identifier (encapsulated in the JSON Web Token Payload) will be different than the newly created account identifier
jobs/generic_purpose/create	Creating a new Generic Purpose Job for a new Accounts Receivable cannot be performed as the authenticated account identifier (encapsulated in the JSON Web Token Payload) will be different than the newly created account identifier
jobs/new_subscription/create	Creating a new Subscription Job for a new Accounts Receivable cannot be performed as the authenticated account identifier (encapsulated in the JSON Web Token Payload) will be different than the newly created account identifier
leads/create	Creating a lead requires to specify a source which can be related with entities that cannot be accessed (i.e. Communications that are related with another Accounts Receivable/Contact Information based entity). In such case a new lead will not be allowed to be created Creating a new Lead for a new Contact Information cannot be performed as the authenticated contact identifier (encapsulated in the JSON Web Token Payload) will be different than the newly created contact identifier
service_requests	Currently implementation of the Service Request methods is verifying the requested Service Request only for the assigned Accounts Receivable, and not with related caller contact. Therefore, when retrieving a Service Request of an Accounts Receivable that the caller is other than the reported Contact, then the Contact Information of the caller will be retrieved as well
price_plans	Information used to indicate whether a Price Plan is associated to an Accounts Receivable (related Contact Information is of type "Company") is kept on the Accounts Receivable entity. As a result, when performing any of the Price Plans methods the system is not able to identify whether the related record should be retrieved or not, therefore Price Plans that are not associated with the Accounts Receivable that is identified through the specified Access Token will be retrieved as well
subscriptions/create	Creating a new Subscription for a new Accounts Receivable cannot be performed as the authenticated account identifier (encapsulated in the JSON Web Token Payload) will be different than the newly created account identifier
usage_service_catalogs	Information used to indicate whether a Usage Service Catalog is associated to an Accounts Receivable (related Contact Information is of type "Company") is kept on the Accounts Receivable entity. As a result, when performing any of the Usage Service Catalog methods the system is not able to identify whether the related record should be retrieved or not, therefore Usage Service Catalogs that are not associated with the Accounts Receivable that is identified through the specified Access Token will be retrieved as well

How to Authenticate with Username & Password Method

Use the POST authentication/token method (by providing a username and password).

Within CRM.COM JWT will be used to generate the authentication tokens which are used to authenticate Web API users. Once the Web API user is authenticated and logged in, then each subsequent request will include the JWT, allowing the user to access routes, services, and resources that are permitted with that token.

Request

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

Body

{
    "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

Response

{
	"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

Browser not supported