Skip to main content

15.10 External Applications

This vtenext function, located in Settings > External Applications, allows you to configure the CRM as an OAuth2 Server, enabling other applications to connect directly to vtenext.

Configuration screen for External Applications

So how does it work exactly? OAuth2 provides authorization flows that allow external applications to access the CRM using tokens. These tokens enable applications to send requests so that the CRM provides the requested data and sends it back to the requesting application. Below is an explanatory image:

This depicted flow is called Client Credentials. There are three parties involved:

  1. Application (e.g., a Management System)

  2. Authorization Server (often equivalent to point 3)

  3. Data Server (in our case, vtenext)

In practice, the Application (which could be a Management System that needs to read invoices from vtenext) requests an access key (Client ID and Secret Key) from the Authorization Server to access the Data Server. In our example, vtenext generates the key pair (Client ID and Secret Key) and provides them to the application, which uses them to request access from the Authorization Server (which is also vtenext). The Authorization Server then grants the Application a Token, allowing it to read invoices directly from the CRM.

The advantage is that the access Token has a limited duration, can be revoked server-side, and enables controlled access to applications. Most importantly, system passwords are not disclosed or shared. Naturally, when the Token expires, a new one must be generated by repeating the above-mentioned procedure.

OAuth2 Authorization Code Flow

The second type of flow is called OAuth2 Authorization Code. This flow involves an additional element, which we will identify as the User.

Example Scenario:

Let's assume that the application connecting to vtenext this time is Facebook, which needs to read Leads stored in vtenext. However, Facebook is linked to a User who is the requester of this data. This means the user is actually asking Facebook to connect to vtenext to retrieve Leads.

In this case, the User also has an account in vtenext. The goal is for the User to grant Facebook permission to read Leads from vtenext. This requires authentication from the User on vtenext, which will then respond to Facebook with an OAuth2 Authorization Code.

Facebook will use this Auth Code to request a temporary Access Token from the Authorization Server, finally allowing it to read the data from the CRM.

Key Benefits:

  • Facebook gains access to vtenext Leads but does not store the User's credentials.

  • After approximately one hour, the access expires, keeping sensitive data secure.

Service Account Configuration

Steps to configure a Service Account:

  1. Click on the ADD button on the right.

  2. A wizard screen appears to guide the configuration process.

  3. Select the Client Type, choosing between:

    • Web or Mobile Application (if access requires user login)

    • Service Account (if access occurs in the background between two servers)

To configure a Client Credentials flow, select:

  • Key Type = Service Account

  • Secret Type = Secret Key

Additional configuration fields will then appear:

Configuration details:

  • Name: Assign a descriptive name to the configuration (e.g., connection to a management system).

  • Client ID & Secret Key: These are auto-generated.

  • Scope: Define the level of data access (read-only, write-only, or read/write).

  • User Association: If read/write access is chosen, only data belonging to the selected user will be accessible (based on the user’s permissions). If full access is needed, an Admin user should be selected.

By providing the Endpoints, Client ID, and Secret Key to the external system’s technician, the connection can be finalized.

For JWT signed authentication, the Secret Key is generated only after saving the configuration.

Web or Mobile Application Configuration

Steps to configure Web or Mobile Application:

  1. Click on the ADD button on the right.

  2. The wizard screen appears again.

  3. Select Web or Mobile Application as the application type.

Application Type Options:

  • Web Application: For browser-based applications.

  • Native or Single Page App: For mobile or native apps.

For a Web Application, the configuration follows a similar process to the Service Account setup:

  • Client ID & Secret Key are generated.

  • Define the Scope (read-only, write-only, or read/write).

Offline Access:

By enabling Offline Access, instead of expiring after a set duration, the Token remains valid indefinitely. The server will issue a refresh token, allowing the application to renew its access without requiring user re-authentication.

Redirect URL Configuration:

  • After logging into vtenext, the User is redirected back to the requesting application (e.g., Facebook).

  • Access control settings allow restricting access to All Users or Selected Users/Groups.

Authorization Screen Customization:

  • The authorization request screen (e.g., "Facebook wants to access your vtenext data. Do you authorize?") can be customized with:

    • Name

    • Description

    • Icon

Managing Registered Applications

From Settings > External Applications, all registered applications are listed.

Managing Application Access:

  • Revoke Access: If, for example, Facebook no longer needs access to vtenext, you can disable access by clicking the green checkmark in the list.

  • Token Expiry: Expired or inactive tokens appear in the list. Users must log in again to renew them.

Available Actions:

  • Edit Configuration

  • Revoke All Tokens

  • Delete Configuration

Linked Applications in User Preferences

In User Preferences, under Linked Applications, users can view all applications associated with their account.

  • View Configuration Details: Users can see (but not modify) the configuration unless they are Admins.

  • Disable or Revoke Tokens: Users can manually revoke application access.

Back to top