Skip to main content

OAuth 2.0

This document guides clients and partners through configuring a Generic OAuth 2.0 Integration to connect their external services (such as Salesforce, HubSpot, or any compliant provider) to our Marketplace Platform.

The configuration process is performed through our platform's Configuration Interface and requires the client to provide API credentials from their Service Provider.

Summary​

The Generic OAuth 2.0 Integration feature allows you to connect the Marketplace to any external service that utilizes the OAuth 2.0 security standard.

TermMeaning for the Client
OAuth 2.0A security protocol that allows the Marketplace to access data in your service (Provider) without needing to store your user credentials.
Generic IntegrationThe ability to connect the Marketplace to any compliant Service Provider, without the need for specific code development for each one.

Advantages for You​

  • Security: Your confidential passwords and API credentials are securely stored and encrypted by our system.
  • Reliability: The system automatically manages the validity and renewal of access tokens, ensuring the connection to your service never unexpectedly expires.
  • Flexibility: You can configure different types of integration (Grant Flows) depending on the security requirements of your Service Provider.

Configuration Guide: Client Requirements​

To set up the integration, you will need to access the Marketplace Configuration Interface and obtain the API information from your Service Provider (such as Salesforce, HubSpot, etc.).

1. Accessing the Configuration Interface (Console)​

  1. Access the Marketplace Admin Console.
  2. Navigate to the section Settings > Integrations.
  3. Select the option "New Generic OAuth 2.0 Integration".

not available

2. Required Configuration Fields​

The configuration interface adapts to the Grant Type you select. You must obtain these values from the developer panel or API documentation of your Service Provider.

FieldDescription
LabelA friendly name to identify this integration in the Marketplace (Example: "Salesforce Production Integration").
Grant TypeThe OAuth 2.0 flow you wish to use (Client Credentials, Authorization Code, Refresh Token).
Token URLThe address (endpoint) of your Provider where the Marketplace will request tokens.
Client IDThe public identifier provided by your Service Provider.
Client SecretThe secret key provided by your Provider. This is confidential and must be kept secret.
Scope(Optional) Defines the specific permissions the Marketplace should have (Example: read, write, api_access).
API Base URLThe main address for accessing the Provider's resources after obtaining the token.
Tenant ID(Optional) Unique identifier that represents a customer.

not available

Supported Grant Types​

The choice of grant type depends on the security model required by your Service Provider.

1. Client Credentials​

  • Usage: Ideal for server-to-server integrations where there is no direct interaction with the Provider's end-user.
  • Additional Required Fields: None besides the basic fields.

2. Authorization Code​

  • Usage: Necessary when the integration requires explicit authorization from an end-user to access data (Example: Sign in with Google/Azure AD).
  • Additional Required Fields:
    • Authorization URL: The address where the user will be redirected to grant permission.
    • Redirect URI: The Marketplace address where the Provider must send the code back after authorization.
    • Scope: Defines the specific permissions the Marketplace should have (Example: read, write, api_access).

IMPORTANT: The Redirect URI must be registered and allowed in your Service Provider's API configuration.

3. Refresh Token​

  • Usage: Allows the Marketplace to request a new Access Token using a long-lived Refresh Token, minimizing the need for re-authorization.
  • Additional Required Fields: Refresh Token (obtained from a previous authorization).

Security and Maintenance Flow​

This section describes what happens "behind the scenes" to ensure your connection remains secure and functional.

1. Initial Acquisition and Validation​

When saving the configuration in the Interface, the Marketplace performs three essential actions:

  1. Validation: It immediately attempts to obtain an Access Token from your Provider using the credentials you supplied.
  2. Secure Storage: If validation is successful, the Client Secret and the initial tokens (access_token, refresh_token) are stored in an enterprise-level secure credential vault (AWS Secrets Manager), not in the main database.
  3. Registration: The non-confidential configurations (Token URL, Client ID, and the pointer to the secure vault) are recorded in the database.

2. Automatic Token Maintenance​

After the integration is saved, the Marketplace takes responsibility for keeping the access active, following this flow for every request:

  1. Expiration Check: Before using the Access Token, the system checks if it is close to expiring (with a 5-minute safety buffer).
  2. Renewal (Refresh): If the token is expired and a Refresh Token is available, the system requests a new token pair from your Provider.
  3. Secure Update: The new access and refresh tokens are saved in the secure credential vault, replacing the old ones.
  4. Usage: The new and valid Access Token is provided to the service that needs to communicate with your Provider.

This automation ensures you do not have to worry about expired tokens.