Authentication

Authentication is a part of the connector definition that specifies establishing connection to an external application:

• What information is needed from the user to establish the connection (and where to get it).
• How to use this information to get (and refresh) credentials.
• How to make API requests using the credentials.
• How to test if connection was successful.

You can use Formulas to make authentication definition dynamic.

Authentication Spec Structure

The authentication spec is defined in the auth field of the connector spec and has the following structure:

auth:
  # The type of authentication
  type: client-credentials  # or oauth2, oauth1, proxy, integration-app-token

  # User interface configuration
  ui:
    # Schema defining what inputs to request from users
    schema:
      type: object
      properties:
        apiKey:
          type: string
          title: "API Key"

    # Help URL with more information about the authentication
    helpUri: "https://docs.example.com/api-authentication"

  # Method implementations for different auth methods
  # These reference files in your connector directory
  makeApiClient:
    implementationType: mapping
  refreshCredentials:
    implementationType: javascript
  test:
    implementationType: javascript

  # Different authentication options/variants
  options:
    option1:
      type: client-credentials
      title: "Option 1"
    option2:
      type: oauth2
      title: "Option 2"

Authentication Types

To get credentials to use for accessing the API, you need to configure authentication. Choose the authentication type that best matches your API's requirements:

• Client Credentials - The simplest authentication type for API keys, basic auth, or custom tokens
• OAuth2 - Standard protocol for third-party authorization without sharing credentials
• OAuth1 - Older authorization protocol with signature-based request authentication (rarely used)
• Proxy - Delegates authentication to another connector
• Integration App Token - Uses integration.app's token system

If not sure which one to pick, go with "Client Credentials" for simple API authentication or "OAuth2" for user-specific access.

User Interface

You can configure how connection UI looks like for your users and ask them for inputs you need to connect to the API.

In some cases, like standard oAuth authentication, you don't need to ask users for anything, and you can skip configuring the UI.

You can configure the following:

• Description - short description of what is happening and what is required from the user.
• Connection Parameters - Data Schema of input you want the user to enter.
• Help URL - link to a relevant help article where user can learn more about the authentication process.

Methods

There are a few Methods that are common between all authentication types:

For type-specific methods, see documentation for that authentication type.

Authentication Options

You can define multiple authentication options for a connector using the options field. This allows users to choose between different authentication methods:

auth:
  type: client-credentials
  # Common auth settings
  options:
    api-key:
      type: client-credentials
      title: API Key Authentication
      # Option-specific settings
      ui:
        schema:
          type: object
          properties:
            apiKey:
              type: string
              title: API Key
    oauth:
      type: oauth2
      title: OAuth Authentication
      # Option-specific settings
      getOAuthConfig:
        implementationType: mapping

Tips for LLM-Generated Authentication Specs

When generating authentication specs based on API documentation:

1. Analyze the authentication flow - Carefully examine the API docs to determine the right authentication type
2. Consider error handling - Include proper error handling for authentication failures
3. Use connection parameters properly - Make sure to define the right schema for user inputs
4. Look for special requirements - Some APIs have special requirements like PKCE support, custom parameters, etc.
5. Implement token refresh - For OAuth2, make sure to properly implement refresh token logic if supported
6. Test thoroughly - Create a comprehensive test function to verify the authentication works
7. Document clearly - Add helpful descriptions and links to API docs
8. Use formula references - Use dynamic values with formulas when appropriate
9. Check scopes - For OAuth2, make sure to request the appropriate scopes for the intended API operations
10. Follow security best practices - Never hardcode secrets, use connector parameters instead