Application Credentials

New approach for granting access for integration into Enate

Overview

As part of this release we're adding a new way in which third Party systems can access Enate - Application Credentials. We've added this to give developers a dedicated way to support how their APIs can be given access to the system. Using this approach for granting API access has some advantages over using standard user accounts:

• A single set of application credentials can have multiple concurrent sessions active.

• You can select specific levels of access to grant each set of application credentials, keeping permissions only as expansive as they need to be.

• Allows a more appropriate support for system-to-system communication.

• Gives better tracking of which APIs are accessed by third party applications.

Technical Specifics

In technical terms, this feature allows Builder admin users to create sets of credentials, specifically 'OAuth Client Credentials' to access Enate & call APIs. Enate uses OAuth2.0 (Open Authorization) for token-based authentication and authorization. For more information on OAuth2.0, please refer to this link https://oauth.net/2/.

The approach is as follows:

1. Use Enate to create an application Credential record (a specific 'ClientID & SecretKey' record, which is effectively a username & password).

2. External to Enate, you must call the Enate oAuth/Token API passing the client id and client secret to obtain a token (specifically a 'Bearer Token').

3. Ensure this Token is included in each API call which is made into the Enate system.

Bearer Tokens

The integration approach uses a type of tokens called 'Bearer Tokens' to access the Enate APIs. These Bearer tokens use HTTPS security, and the request is not signed or encrypted: possession of the bearer token is considered authentication. For more about OAuth 2.0 access tokens, refer to this link https://oauth.net/2/access-tokens/.

Note that the bearer token will expire if it is not used to make an API call for the length of time set in the 'Idle Session Timeout' setting in the General Settings section of Enate Manager.

If the bearer token does expire, the application credentials can be re-authenticated by using the '/OAuth/Token' Enate API to generate a new bearer token.

Additionally, any changes made to a user's roles (i.e. if a user gets assigned a new role or they are removed from a role) will cause the bearer token to expire.

If a bearer token does expire, the application credentials can be re-authenticated by using the '/OAuth/Token' Enate API to generate a new bearer token. Note that revoked roles will not get assigned to a new bearer token.

Creating a new Application Credentials Record

To support this feature we've added a new section in the User Management section of Builder to help manage different sets of Application Credentials you may wish to create:

The resulting screen will show a list of any existing Application Credentials, the roles it includes and the expiry date. To create a new credential, click on '+' link, and fill in details in the resulting popup:

Enter a Name for the credential, add an expiration date and select which Role(s) which you with the credential to have - these are equivalents to various permissions roles which a user can be given access to. Options available are:

Role	Access Rights
Service Agent	Able to access Work Manager - standard Team Member level access
Self Service User	Able to access Self Service app (available in future release)
Work Creator	Access to create new Cases, Tickets, Actions in Work manager
Work Assigner	Access to assign work items in Work Manager
Team Leader	Access to Team Leader-level data in Work Manager (e.g. bots view, Queues page).
Builder	Access to Builder
User Manager	Access to only User Management section of Builder
Master Builder	Access to create & edit master data which can be shared between processes
Release Manager	Ability to publish Case & Ticket processes in Builder

Additionally, if a user has been removed from a role, these revoked roles will appear in grey in the application credentials edit pop-up:

Then click to generate a key. This will create:

• A Client ID

• A Secret Key

You should copy these two pieces of data at this point, for use in subsequent steps to create a Bearer Token outside of Enate.

Note: You will only be able to access this secret key once, at this point. Once the pop-up window is closed you will no longer have access to it, and if you have not taken a note and subsequently wish to use this client ID, you would need to generate a new secret key.

Once the Credential record has been generated, it will be saved and stored in the Application Credentials page. You can subsequently edit its name and expiry date and generate a new secret key for it. Credential records can also be deleted if desired.

Generating the Bearer Token - Sample

You should use the copied Client ID and Secret Key as inputs into your third party system, for example the Postman API testing tool. From example above, this would be:

Client ID: eba59171-ac3a-4527-939a-830494c2c5f6

Secret Key: 3@rn0i+0y5jRB8_n

The Third-party system should be making a POST API call to the '/OAuth/Token' Enate API to generate the bearer token.

For the API request, select 'x-www-form-urlencoded' in the body section to pass the three parameters below while making the API call to generate the token.

• grant_type - client_credentials

• client_id - 0f6c907b-00f4-4e12-8d75-41454b777533

• client_secret - TLd55KNez61niSXO

Example:

This generates the Bearer token, which is then used to get authorization for API calls to Enate.

Using the Bearer Token

To make a new API call to Enate, select Type as ‘Bearer Token’ in the Authorization section of the API request, pass your generated bearer token and the request URL for the specific API you're looking for.