Authentication Methods Explained: Configuring Your Connector

Data Hub Connectors & Databases
1

When building a connector, establishing the Base URL is only the first step. To access private data, your workspace needs to prove its identity to the external system. This process is called Authentication.

Because every external software is built differently, there is no single way to authenticate. You must use the specific method required by the system you are trying to connect to.

This guide explains the available authentication methods in Mogno, what information you need to configure them, and how to validate your secure connection.

Before You Begin: The Golden Rule of Integration

Before selecting a method in the Mogno builder, you must consult the external system’s documentation.

  1. Log into the external software you want to connect to.
  2. Search for their “Developer Portal”, “API Documentation”, or “Integrations” page.
  3. Look for the “Authentication” or “Authorization” section.
  4. The documentation will explicitly state which method they require (e.g., “We use OAuth 2.0” or “Generate an API Key”).

Once you know what they require, return to Mogno and select the corresponding method from the dropdown.

The Authentication Methods

Here is a detailed breakdown of each method available in the builder and what you will need to configure it.

1. None

  • What it is: No authentication required.
  • When to use it: Only when connecting to completely public APIs that do not require an account or secret key.
  • What you need: Nothing. Simply select “None” and proceed.

2. System-to-System Access (OAuth)

  • What it is: The industry standard for secure, automated background authorization between servers. Instead of copying and pasting a static password, it uses a secure “handshake” to grant Mogno temporary access tokens.
  • What you need: The external system’s developer portal will provide you with specific application credentials. You will need to configure:
    • Authentication Location: Where the credentials should be sent (Header or Body).
    • URL: The specific authorization address provided by the external system.
    • Client ID & Client Secret: The unique identifiers acting as your application’s login and password.
    • Request Body (optional): Some systems require a specific JSON structure to complete the handshake.
  • Important Note: Unlike other methods, System-to-System Access does not require a Test URL field.

3. User Login (OAuth)

  • What it is: Similar to System-to-System, but designed for scenarios where an actual user must manually authorize the connection via a login screen.
  • What you need:
    • Callback URL: Mogno provides a read-only URL (https://platform.mogno.ai/oauth2/callback). You must copy and paste this into the external system’s developer settings to allow the connection back to Mogno.
    • Client ID & Client Secret: Your unique application identifiers.
    • How credentials are sent: Choose between Header or Body.
    • Authorization URL & Token URL: The external system’s specific endpoints for handling the login and token generation.
    • Permissions (Scopes): Define exactly what level of access you are requesting (e.g., read:users).
    • Enhanced Security (PKCE): A checkbox for APIs that enforce Proof Key for Code Exchange for added security.
  • The Final Step: Once configured, you must click the SIGN IN WITH CREDENTIALS button to manually perform the login and authorize the app.

4. Basic Auth

  • What it is: A traditional form of web authentication that transmits a username and password.
  • When to use it: Mostly used when connecting to older, legacy systems that do not support modern token-based security.
  • What you need: You will need the specific Username and Password provided by the external system for API access.

5. API Key (or API Token)

  • What it is: A unique, long string of characters generated by the external system that acts as a permanent password for your integration.
  • What you need: You must generate this key inside the external system’s security settings. In the Mogno interface, paste the key into the Key field and select the required HTTP Verb (e.g., GET or POST).
  • Lifecycle Note: API Keys do not expire automatically. If you manually revoke the key in the external system, your connector will break until you paste a new key into Mogno.

6. Bearer Token

  • What it is: Very similar to an API Key, but it requires a specific formatting rule where the token is sent in the Header of the request, preceded by the word “Bearer”.
  • What you need: Select the Authentication Location (usually the Header), paste your Bearer Token, and define the HTTP Verb as dictated by the external documentation.

7. Custom

  • What it is: A blank canvas for authentication.
  • When to use it: When the external system uses a proprietary security method or requires dual authentication (multiple keys sent at once).
  • What you need: You must manually define the Parameter Location (e.g., Header), the Parameter Key (the exact name the external API expects, like x-custom-auth), and the Parameter Value (your secret code).
  • Pro-Tip for Dual Authentication: Many modern APIs require multiple security parameters simultaneously (for example, a standard Authorization Bearer token AND a custom Client-ID header). The Custom method handles this perfectly. Configure your first parameter, then click the + Add Parameter button to add the second one. You can stack as many authentication rules as the external system requires.

Validating Credentials & The Test URL

Before moving to the next tab, you have the option to verify if your credentials actually work.

  1. Find a Test Endpoint: Go to the external system’s API documentation and look for a simple endpoint that retrieves basic data (e.g., an endpoint to “List Users” like /v2/users, or “Get Profile” like /me).
  2. Paste it in Mogno: Go back to the Mogno interface and paste that endpoint path into the Test URL field.

Crucial Rule: Always Use the Full Endpoint Path
When filling in the Test URL field, always provide the complete URL (e.g., https://api.system.com/v2/users), not just the relative path (/v2/users). While some permissive APIs accept relative paths, most production-grade authenticated APIs require the full URL to correctly route the request. Using the full URL guarantees consistent behavior and avoids false “invalid credentials” errors.

  1. Test: Click the Validate Credentials button.

Mogno will perform a quick connection check using that endpoint. Once the test is complete, this URL is discarded—it is not stored or used for your actual data operations. While validating here is optional, it ensures your bridge is authenticated and secure before you start building specific queries.

Exception: System-to-System Access (OAuth) > If you selected the System-to-System method, you will notice there is no Test URL field. This is intentional. You can skip steps 1 and 2. Simply click the Validate Credentials button directly. Mogno will validate your connection by asking the external server to generate a token using your Client ID and Secret. If successful, your bridge is ready.

Troubleshooting: “The provided credentials are invalid”

If you receive a generic connectivity error during validation, here is how to diagnose it:

  • Check the Test URL: Verify that you used the full endpoint URL, there are no typos, and no duplicate parameters (e.g., ?format=json&format=json).
  • Verify Authentication Parameters: Confirm your API Key hasn’t been revoked. If using Custom authentication, ensure all required headers are present (as mentioned, some APIs require multiple simultaneous headers). Re-read the external API’s documentation to confirm the exact parameter names and locations.

Security Storage

No matter which method you use, your credentials are secure. The platform does not store your keys in plain text; everything is encrypted at rest (AES-256) and managed within a highly secure Google Cloud Secret Manager vault.

Next Steps: Mapping Your Data

Once your authentication method is selected, your secure bridge is open. Proceed to the next topic to learn how to configure Data Resources (Endpoints) and fetch your information reliably.