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
}
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.
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.
| 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. |
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 agency ID if the application was installed by an agency; null if installed by a location. |
{field_key} | string | The key for each configured field. A maximum of three fields are supported. |
approveAllLocations | boolean | true if “Select all sub-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
}
{
"companyId": "123",
"locationId": ["A", "B"],
"username": "user1",
"password": "password123",
"approveAllLocations": false,
"excludedLocations": null
}
{
"companyId": "123",
"locationId": null,
"username": "user1",
"password": "password123",
"approveAllLocations": true,
"excludedLocations": null
}
{
"companyId": "123",
"locationId": null,
"username": "user1",
"password": "password123",
"approveAllLocations": true,
"excludedLocations": ["C", "D"]
}
.png?fit=max&auto=format&n=EQK5eX9kTD8NzWwA&q=85&s=878008bf159fcc4964d0c0d508b6e400)