Client Credentials Authentication

Client credentials authentication is the simplest authentication type. It lets you ask for user input, optionally transform it into connection credentials, and use those to access the API.

Overview

This authentication type is ideal for APIs that use:

API keys
Username and password
Basic authentication
Custom token-based authentication that doesn't follow OAuth standards

Connector Definition

Example client credentials connector definition:

# Connector definition: Simple API key authentication with user input form
type: client-credentials
title: 'API Key Authentication'
description: 'Enter your API key to authenticate'

# User input form: what to ask from the user
ui:
  schema:
    type: object
    properties:
      apiKey:
        type: string
        title: 'API Key'
  helpUri: 'https://docs.example.com/api-authentication'

# Optional: transform user input into credentials
getCredentialsFromConnectionParameters:
  type: javascript
  code: |
    export default async function ({ connectionInput }) {
      return { apiKey: connectionInput.apiKey }
    }

# Configure API client with credentials
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com/v1
    headers:
      Authorization:
        $concat:
          - "Bearer "
          - $var: credentials.apiKey

# Test the connection
test:
  type: javascript
  code: |
    export default async function ({ apiClient }) {
      const user = await apiClient.get("/user")
      return user.id !== undefined
    }

How It Works

By default, user input (connectionInput) is used directly as connection credentials. If you need to transform this input or add additional information, you can implement the getCredentialsFromConnectionParameters method.

Custom Credential Processing

You can implement a custom getCredentialsFromConnectionParameters method to transform user input into API credentials:

# Connector definition: Transform user input into credentials with additional fields
getCredentialsFromConnectionParameters:
  type: javascript
  code: |
    export default async function ({
      connectorParameters,
      connectionInput,
    }) {
      return {
        apiKey: connectionInput.apiKey,
        // Add additional fields or transformations
        authHeader: `Bearer ${connectionInput.apiKey}`,
      }
    }

This function receives the following input parameters:

connectorParameters - parameters configured for the connector in your workspace.
connectionInput - input provided by the user in the connection UI.

API Client Configuration

For client credentials authentication, you'll typically need to configure the API client to include the credentials in requests:

# Connector definition: Configure Bearer token authentication
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com/v1
    headers:
      Authorization:
        $tpl:
          template: 'Bearer {token}'
          values:
            token:
              $var: credentials.apiKey
      Content-Type: application/json

Common Authentication Patterns

API Key in Header

# Connector definition: Send API key in X-API-Key header
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com/v1
    headers:
      X-API-Key:
        $var: credentials.apiKey
      Content-Type: application/json

API Key in Query Parameter

# Connector definition: Send API key as query parameter in every request
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com/v1
    query:
      api_key:
        $var: credentials.apiKey
    headers:
      Content-Type: application/json

Basic Authentication

# Connector definition: Basic auth with username/password
ui:
  schema:
    type: object
    properties:
      username:
        type: string
        title: 'Username'
      password:
        type: string
        title: 'Password'
        format: password

makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com/v1
    headers:
      Authorization:
        $tpl:
          template: 'Basic {token}'
          values:
            token:
              $jsonata: $base64encode(credentials.username & ':' & credentials.password)
      Content-Type: application/json