Authentication methods

Authentication for API connections in Data Integration can be configured using multiple supported methods. Data Integration supports OAuth 2.0, basic authentication, and bearer tokens, along with secure token management for each method.

Supported authentication methods

The following table describes the available authentication methods:

Auth type	Description	Common use cases
No auth	Connects to public APIs that require no credentials.	Public data APIs, health check endpoints.
Bearer token	Uses a simple token in an Authorization header.	API tokens, personal access tokens.
Basic HTTP	Uses username and password for authentication.	Traditional APIs, Jira, Jenkins.
API Key	Sends a static key via a header or query parameter.	Many REST APIs, AWS services.
OAuth2	Uses token-based flows with various grant types.	Modern APIs, Google, Salesforce.

No authentication

For public APIs that don't require any credentials.

# No interface_parameters needed for authentication
# Simply omit the authentication parameter

connector:
  name: "Public API Connector"
  base_url: "https://api.publicdata.com/v1"

Bearer token authentication

Bearer token authentication sends a token in the Authorization: Bearer <token> header.

When to use

Personal access tokens: Connecting to services like GitHub or GitLab.
API tokens: Accessing platforms such as Notion or Airtable.
Pre-generated tokens: Using static authentication tokens provided by a service.
Direct JWTs: Passing JSON Web Tokens directly in the header.

Configuration example

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "bearer"
        fields:
          - name: "bearer_token"
            type: "string"
            is_encrypted: true

Example: GitHub personal access token

interface_parameters:
  section:
    source:
      - name: "github_auth"
        type: "authentication"
        auth_type: "bearer"
        fields:
          - name: "bearer_token"
            type: "string"
            is_encrypted: true

connector:
  name: "GitHub API"
  base_url: "https://api.github.com"
  default_headers:
    Accept: "application/vnd.github+json"
    X-GitHub-Api-Version: "2022-11-28"

Basic HTTP authentication

Use Basic HTTP authentication to send a Base64-encoded username and password in the Authorization header.

Configuration

Define the basic_http authentication type within your interface parameters.

When to use

Apply Basic HTTP authentication for the following scenarios:

Atlassian products: Connecting to services such as Jira or Confluence.
CI/CD tools: Accessing platforms like Jenkins or TeamCity.
Legacy systems: Integrating with older enterprise APIs.
Token combinations: Accessing APIs that require an email address combined with an API token.

Configuration example

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "basic_http"
        fields:
          - name: "username"
            type: "string"
          - name: "password"
            type: "string"
            is_encrypted: true

Basic HTTP authentication examples

Jira Cloud

To connect to Jira Cloud, use your email address as the username and an API token as the password.

interface_parameters:
  section:
    source:
      - name: "your_domain"
        type: "string"
        value: ""
      - name: "jira_auth"
        type: "authentication"
        auth_type: "basic_http"
        fields:
          - name: "username"
            type: "string"
            value: ""          # Email address
          - name: "password"
            type: "string"
            value: ""          # API token (not password)
            is_encrypted: true

connector:
  name: "Jira Cloud Connector"
  base_url: "https://{your_domain}.atlassian.net/rest/api/3"
  default_headers:
    Accept: "application/json"

Jenkins

To connect to Jenkins, provide your username and the generated API token.

interface_parameters:
  section:
    source:
      - name: "jenkins_url"
        type: "string"
        value: ""
      - name: "jenkins_auth"
        type: "authentication"
        auth_type: "basic_http"
        fields:
          - name: "username"
            type: "string"
          - name: "password"
            type: "string"
            is_encrypted: true     # API token

connector:
  name: "Jenkins Connector"
  base_url: "{jenkins_url}"

API key authentication

API key authentication sends a static key to an API. You can configure the system to send the key as a custom header or append it as a query parameter.

API key in header

The system sends the key as a custom header with every request.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "api_key"
        location: "header"
        fields:
          - name: "key_name"
            type: "string"
            value: "X-API-Key"       # Header name
          - name: "key_value"
            type: "string"
            is_encrypted: true       # The actual API key

API key in query parameter

The system appends the key to the request URL as a query parameter.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "api_key"
        location: "query_param"
        fields:
          - name: "key_name"
            type: "string"
            value: "api_key"         # Query parameter name
          - name: "key_value"
            type: "string"
            is_encrypted: true       # The actual API key

Common header names

API/Service	Header name
Generic	`X-API-Key`
AWS	`X-Api-Key`
Sendgrid	`Authorization` (with "Bearer " prefix)
OpenAI	`Authorization` (with "Bearer " prefix)
Custom	Varies by API

API key authentication examples

Example 1: OpenAI API

Configure OpenAI by setting the location to header and using the Authorization key name.

interface_parameters:
  section:
    source:
      - name: "openai_auth"
        type: "authentication"
        auth_type: "api_key"
        location: "header"
        fields:
          - name: "key_name"
            type: "string"
            value: "Authorization"
          - name: "key_value"
            type: "string"
            is_encrypted: true       # Format: "Bearer sk-..."

connector:
  name: "OpenAI API"
  base_url: "https://api.openai.com/v1"
  default_headers:
    Content-Type: "application/json"

Example 2: Weather API with query parameter

Configure OpenWeather by setting the location to query_param to append the key to the URL.

interface_parameters:
  section:
    source:
      - name: "weather_auth"
        type: "authentication"
        auth_type: "api_key"
        location: "query_param"
        fields:
          - name: "key_name"
            type: "string"
            value: "appid"
          - name: "key_value"
            type: "string"
            is_encrypted: true

connector:
  name: "OpenWeather API"
  base_url: "https://api.openweathermap.org/data/2.5"

OAuth2 authentication

OAuth2 is a token-based authentication protocol supports multiple grant types for different authentication flows.

Supported grant types

Grant type	Description	Use case
`client_credentials`	Server-to-server authentication.	Backend integrations, APIs.
`refresh_token`	Long-lived access using refresh tokens.	User-authorized access renewal.
`authorization_code`	User-authorized access through login flow.	User-specific data access.

OAuth2 settings reference

Setting	Description	Required
`grant_type`	The OAuth2 flow type	Yes
`token_url`	Endpoint to obtain access tokens	Yes
`is_basic_auth`	Send credentials as Basic Auth header (instead of body)	No
`scopes`	Permission scopes (space-separated)	No

Client credentials grant

Server-to-server authentication where your application authenticates directly without user involvement.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "client_credentials"
          token_url: "https://auth.example.com/oauth2/token"
          is_basic_auth: false
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true

With basic auth header

Some OAuth2 providers require credentials sent as a Basic Auth header instead of in the request body:

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "client_credentials"
          token_url: "https://auth.example.com/oauth2/token"
          is_basic_auth: true      # Send as Basic Auth header
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true

OAuth2 authentication examples

Example 1: Salesforce

Connect to Salesforce by specifying your instance domain and providing OAuth2 credentials.

interface_parameters:
  section:
    source:
      - name: "salesforce_domain"
        type: "string"
        value: ""
      - name: "salesforce_auth"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "client_credentials"
          token_url: "https://login.salesforce.com/services/oauth2/token"
          is_basic_auth: false
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true

connector:
  name: "Salesforce Connector"
  base_url: "https://{salesforce_domain}.salesforce.com/services/data/v58.0"

Refresh token grant

Use a refresh token to obtain new access tokens without requiring user re-authentication.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "refresh_token"
          token_url: "https://auth.example.com/oauth2/token"
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true
          - name: "refresh_token"
            type: "string"
            is_encrypted: true

Example: Google APIs

Use a refresh token to maintain persistent access to Google service endpoints.

interface_parameters:
  section:
    source:
      - name: "google_auth"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "refresh_token"
          token_url: "https://oauth2.googleapis.com/token"
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true
          - name: "refresh_token"
            type: "string"
            is_encrypted: true

connector:
  name: "Google Sheets Connector"
  base_url: "https://sheets.googleapis.com/v4"

Authorization code grant

Exchange an authorization code (obtained through user login) for access tokens.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "authorization_code"
          token_url: "https://auth.example.com/oauth2/token"
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true
          - name: "code"
            type: "string"
          - name: "redirect_uri"
            type: "string"

OAuth2 response field mapping

Some OAuth2 providers return token response fields with non-standard names. Use the key_map property to map provider-specific field names to the expected field names.

When to use

Use key_map when an OAuth2 provider returns fields with different names than expected.

Standard field	Common provider variants
`access_token`	`accessToken`, `token`, `access`
`refresh_token`	`refreshToken`, `refresh`
`expires_in`	`expiresIn`, `expires`, `expiry`
`token_type`	`tokenType`, `type`

OAuth2 response field mapping example

Define the key_map within the specific field object to translate the incoming provider key.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "client_credentials"
          token_url: "https://api.custom-provider.com/oauth/token"
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true
          - name: "access_token"
            type: "string"
            key_map: "accessToken"      # Maps "accessToken" to "access_token"
          - name: "expires_in"
            type: "string"
            key_map: "expiresIn"        # Maps "expiresIn" to "expires_in"
          - name: "token_type"
            type: "string"
            key_map: "tokenType"        # Maps "tokenType" to "token_type"

How field mapping works

The system processes field mapping through the following sequence:

Token request: The system sends a request to the configured token_url.
Response capture: The provider returns a JSON payload with custom keys. For example, {"accessToken": "abc123"}.
Translation: The key_map translates the custom keys into standard system fields.
Execution: The system uses the standardized fields to authorize subsequent API requests.

Example: Custom OAuth2 provider

Map fields for legacy systems that use unique naming conventions for bearer tokens and expiration values.

interface_parameters:
  section:
    source:
      - name: "custom_auth"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "client_credentials"
          token_url: "https://auth.legacysystem.com/v1/tokens"
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true
          # Provider returns: {"bearerToken": "...", "validFor": 3600}
          - name: "access_token"
            type: "string"
            key_map: "bearerToken"
          - name: "expires_in"
            type: "string"
            key_map: "validFor"

Security Best practices

Encrypt sensitive fields: Set is_encrypted: true for all passwords, tokens, secrets, and keys.

Example

fields:
  - name: "password"
    type: "string"
    is_encrypted: true     # Always encrypt
    
  - name: "api_key"
    type: "string"
    is_encrypted: true     # Always encrypt
    
  - name: "client_secret"
    type: "string"
    is_encrypted: true     # Always encrypt
    
  - name: "refresh_token"
    type: "string"
    is_encrypted: true     # Always encrypt

Avoid hardcoding credentials: Never embed static secrets or keys directly in the YAML. Use interface parameters so users can provide credentials via the UI.

Example

  # WRONG - Never do this
  connector:
    default_headers:
      Authorization: "Bearer sk-abc123secretkey"

  # CORRECT - Use interface parameters
  interface_parameters:
    section:
      source:
        - name: "api_credentials"
          type: "authentication"
          auth_type: "bearer"
          fields:
            - name: "bearer_token"
              type: "string"
              is_encrypted: true

Use automated header injection: Do not manually define Authorization headers. The system automatically injects the correct headers based on your auth_type configuration.

Example

# WRONG - Don't manually add Authorization
connector:
  default_headers:
    Authorization: "Bearer {{%token%}}"

# CORRECT - Let the system handle it
interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "bearer"
        # System automatically adds: Authorization: Bearer <token>

Use OAuth2 when available: Use OAuth2 whenever supported by the API to benefit from automatic token rotation, limited access scopes, and refresh capabilities.
Validate connectivity: Add a pre_run_configurations step to verify credentials against a lightweight endpoint (such as /me or /status) before starting the main workflow.
Example
Consider using a pre-run step to validate credentials:
pre_run_configurations: name: "Validate Authentication" steps: - name: "Auth Check" type: "rest" http_method: "GET" endpoint: "{{%BASE_URL%}}/me"

Troubleshooting

Common authentication errors

Error	Possible cause	Solution
401 Unauthorized	Invalid or expired credentials.	VVerify the token or password; use a refresh_token flow to renew access.
403 Forbidden	Insufficient permissions.	Verify the API scopes or user permissions in the target system.
400 Bad Request (OAuth2)	Incorrect OAuth2 settings.	Verify the grant_type and token_url match the provider's documentation.

OAuth2 connectivity issues

Verify the token URL: Ensure the token_url endpoint is correct and reachable.
Check auth location: Determine if the provider requires credentials in the request body or via a Basic Auth header (is_basic_auth: true).
Confirm scopes: Ensure you have requested all required permissions in the scopes field.
Review field names: Use key_map if the provider returns non-standard keys in the JSON response.

API key issues

Check location: Confirm the key is sent in the correct location (header or query_param).
Validate key name: Ensure the key_name matches the exact string expected by the API. For example, X-API-Key.
Check prefixes: Some APIs require the key_value to include a prefix, such as Bearer.