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

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"
      enabled:
         $var: connectorParameters.clientId # Only enable this option if clientId is provided in connector configuration.

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

Authentication Implementation Workflow

If you are an AI agent implementing authentication, use this workflow to populate your ToDo list and follow it step by step.

• Determine which authentication mechanisms and workflows does API support. Create an authentication option for each of them. Follow the rest of the workflow for each authentication option.
  • If some auth options require connector parameters to work, disable them by default and enable only if parameters are provided.
• Select authentication type.
• Determine what information is needed from the developer (person implementing the integration in their app). It is typically clientId/clientSecret/scopes for OAuth, selecting of environment (dev or prod) or any other parameters developer can know ahead of time. Add this data to the connector parameters schema.
• Determine what information is needed from the user when creating a connection. This is typically things like API keys, selection of environment (sandbox/production), identifier of environment to connect to, etc. Define this information in connection parameters schema.
• Analyze a few documented API requests to see if they typically require parameters that are not in standard credentials (like parameters in path or headers that need to be provided across multiple requests). If you found those - add them to the custom credentials by:
  • Adding customCredentialsSchema with just non-standard credentials.
  • Implementing getCredentialsFromConnectionParameters or getCredentialsFromTokenResponse methods.
• Implement makeApiClient function using its implementation guide.
• Determine if API requires any other non-standard functionality and implement it with functions mentioned in this guide.
• Implement test function using its implementation guide.