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:
Method | Description |
---|---|
makeApiClient | Configures how your connector makes API requests to the external service, including authentication headers, base URL, and other settings. |
getCredentialsFromConnectionParameters | (optional) Transforms user-provided connection parameters into the credential format required for authentication. |
refreshCredentials | (optional) Defines how to refresh expired or invalid authentication credentials without requiring user intervention. |
test | (optional, but recommended) Validates if authentication credentials are working correctly by making a test API request. |
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
orgetCredentialsFromTokenResponse
methods.
- Adding
- 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.
Updated 9 days ago