External Authentication

External authentication enables developers to authenticate HoopAI Platform users using their credentials with the developer’s system before installing the application on the HoopAI Platform. This feature allows you to configure custom authentication fields as necessary, such as:

API key
Username
Password
OAuth 2.0

How to Enable External Authentication

Navigate to Developer Marketplace > My Apps, select your app, and click on the External Authentication tab in the navigation pane. Both API Key/Basic Auth and OAuth 2.0 are supported.

OAuth 2.0

This section outlines the process of configuring OAuth 2.0 authentication for external calls within Marketplace apps. Currently, only the Authorization Code grant type is supported. The HoopAI Platform manages token pairs and includes them in custom actions and triggers, enabling a wide range of integration possibilities.

1. Configuration

Follow these steps to configure OAuth 2.0 authentication: a. App Details and Scopes Provide the name of your third-party app, client key, and client secret. Specify the required scopes for your third-party integration. Separate scopes with spaces or commas. Include only the necessary scopes for the integration. b. Redirect URL Copy the redirect URL provided in your Marketplace app configuration and paste it into your third-party app’s configuration settings. c. Authorization URL Configuration Configure the authorization URL. The Marketplace pre-populates some standard fields, which you can adjust based on the third-party app’s documentation. The state parameter is a standard OAuth 2.0 security feature that prevents authorization requests from being initiated by unauthorized parties. Ensure this parameter is not modified for seamless integration. d. Access and Refresh Token Request Configuration Configure the access and refresh token request settings according to the third-party app’s documentation. The Marketplace pre-populates some standard configurations, which you can modify as needed. Click More Options to add any additional call details required. Example expected response:

{
  "access_token": "your_access_token",
  "refresh_token": "your_refresh_token",
  "expires_in": 3600
}

e. Auto Refresh Token Enable the Auto refresh token option to automatically fetch new token pairs using the refresh API when tokens expire. If auto-refresh is disabled, the connection will break after token expiration and the user will need to re-authorize. Enabling this option is recommended for a smooth, uninterrupted experience. f. Test API Configure a test API endpoint (ideally a GET call requiring no special configuration) to validate the token. The HoopAI Platform will call this API to check token validity. If the test fails and auto-refresh is enabled, the Marketplace will attempt to refresh the token.

2. Testing the Integration

Developers can test their configurations using the built-in test functionality. This initiates the OAuth process with the third-party app. Once the token is generated, the configured test API is called. Ensure all configurations are saved before testing.

Switching between external authentication types (e.g., from Basic to OAuth) is currently not supported.

OAuth Parameters Reference

Parameter	System Value	Description
`client_id`	`{{externalApp.clientId}}`	Unique identifier issued by the third-party application.
`client_secret`	`{{externalApp.clientSecret}}`	A confidential key used to authenticate your application when exchanging the authorization code for tokens. Must be kept secure and never exposed to clients.
`scope`	`{{externalApp.scope}}`	A space-separated list of permissions your application requires.
`response_type`	`code`	Specifies the type of response expected. Only the `code` response type is supported.
`state`	`{{bundle.state}}`	A security token generated by the HoopAI Platform to prevent CSRF attacks. Must be returned unchanged in the callback response.
`redirect_uri`	`{{bundle.redirectUrl}}`	The callback URL where the third-party application will send the authorization response. Must be pre-registered and match exactly.
`grant_type`	`authorization_code` or `refresh_token`	Type of grant being requested: `authorization_code` for initial exchange, `refresh_token` for obtaining new access tokens.

Token Parameters Reference

Parameter	System Value	Description
`code`	`{{bundle.code}}`	The authorization code received from the third-party application. Temporary and can only be used once.
`access_token`	`{{bundle.accessToken}}`	The token used to authenticate requests to the third-party API. Has a limited lifetime and needs to be refreshed periodically.
`refresh_token`	`{{bundle.refreshToken}}`	A long-lived token used to obtain new access tokens when the current one expires. Remains valid until explicitly revoked.

API Key or Basic Auth

There are three sections available for API Key or Basic Auth configuration.

Section 1: Configure Your Fields

This section contains all the fields that developers want to ask from users while installing the application. To add a field to the user’s authentication form, configure the following:

Setting	Description
Label	Helpful text describing the field.
Key	The key that holds the value of the user’s input. You may pass the user’s input to your authentication endpoint in the header or body using this key.
Type	The type of input shown to the user. Supported types: `text` and `password`.
Required	Whether the field is required.
Help Text	A brief description of the field displayed to the user.
Default field	Default value sent if the user leaves the field empty.

A maximum of three fields is supported.

Section 2: Configure Authentication Endpoint

This section lets you configure the HTTP request template made when a user tries to install the application.

Setting	Description
Type of request	`GET`, `POST`, `PUT`, or `PATCH`. When `GET` is selected, the request body cannot be configured.
URL	The URL that will be called with the request.
URL params	The params to send with the request.
HTTP headers	The headers to send with the request.
Request Body	The body to send with the request.

To pass user-entered values such as an API key, username, or password, access them via the userData object using {{userData.key}}. For example, if your field’s key is apiKey, access the value with {{userData.apiKey}}. For external auth verification to complete, the authentication URL must return one of the following status codes: 200, 201, 202, 204.

Section 3: Test Your Authentication

This section allows developers to test the authentication flow with sample values.

External Auth Request Parameters

Key	Type	Details
`companyId`	string	Set to the company ID if the application was installed at the company level; `null` if installed at the location level.
`{field_key}`	string	The key for each configured field. A maximum of three fields are supported.
`approveAllLocations`	boolean	`true` if “Select all accounts” was selected during installation; `false` otherwise.
`locationId`	string[]	If `approveAllLocations` is `false`, contains an array of selected location IDs. If `true`, set to `null`.
`excludedLocations`	string[]	If `approveAllLocations` is `false`, set to `null`. If `true`, contains an array of location IDs that were not selected.

In POST, PATCH, and PUT requests, these fields are sent in the request body. In GET requests, they are passed as query parameters.

Examples

Scenario 1: User selects location A while installing the app.

{
  "companyId": "123",
  "locationId": ["A"],
  "username": "user1",
  "password": "password123",
  "approveAllLocations": false,
  "excludedLocations": null
}

Scenario 2: User selects locations A and B.

{
  "companyId": "123",
  "locationId": ["A", "B"],
  "username": "user1",
  "password": "password123",
  "approveAllLocations": false,
  "excludedLocations": null
}

Scenario 3: User selects “Select all 5 locations.”

{
  "companyId": "123",
  "locationId": null,
  "username": "user1",
  "password": "password123",
  "approveAllLocations": true,
  "excludedLocations": null
}

Scenario 4: User selects “Select all 5 locations” but unchecks locations C and D.

{
  "companyId": "123",
  "locationId": null,
  "username": "user1",
  "password": "password123",
  "approveAllLocations": true,
  "excludedLocations": ["C", "D"]
}

Developer Basics

Guides

API Overview

Concepts & Guides

Authentication

External Authentication

External Authentication

How to Enable External Authentication

OAuth 2.0

1. Configuration

2. Testing the Integration

OAuth Parameters Reference

Token Parameters Reference

API Key or Basic Auth

Section 1: Configure Your Fields

Section 2: Configure Authentication Endpoint

Section 3: Test Your Authentication

External Auth Request Parameters

Examples

​External Authentication

​How to Enable External Authentication

​OAuth 2.0

​1. Configuration

​2. Testing the Integration

​OAuth Parameters Reference

​Token Parameters Reference

​API Key or Basic Auth

​Section 1: Configure Your Fields

​Section 2: Configure Authentication Endpoint

​Section 3: Test Your Authentication

​External Auth Request Parameters

​Examples

External Authentication

How to Enable External Authentication

OAuth 2.0

1. Configuration

2. Testing the Integration

OAuth Parameters Reference

Token Parameters Reference

API Key or Basic Auth

Section 1: Configure Your Fields

Section 2: Configure Authentication Endpoint

Section 3: Test Your Authentication

External Auth Request Parameters

Examples