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

Configuration

In your spec.yml:

auth:
  type: client-credentials
  title: "API Key Authentication"
  description: "Enter your API key to authenticate"

  # Define the UI for collecting user input
  ui:
    schema:
      type: object
      properties:
        apiKey:
          type: string
          title: "API Key"
    helpUri: "https://docs.example.com/api-authentication"

  # Reference to method implementations
  getCredentialsFromConnectionParameters:
    implementationType: javascript
  makeApiClient:
    implementationType: mapping
  test:
    implementationType: javascript

How It Works

By default, user input (connectionParameters) 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:

// File: auth/get-credentials-from-connection-parameters.js
exports.getCredentialsFromConnectionParameters = async function ({
  connectorParameters,
  connectionParameters,
}) {
  // Transform connection parameters into credentials
  return {
    apiKey: connectionParameters.apiKey,
    // Add additional fields or transformations
    authHeader: `Bearer ${connectionParameters.apiKey}`,
  }
}

This function receives the following input parameters:

connectorParameters - parameters configured for the connector in your workspace.
connectionParameters - 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. This is done in the makeApiClient implementation:

# File: auth/make-api-client.map.yml
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

# File: auth/make-api-client.map.yml
baseUri: https://api.example.com/v1
headers:
  X-API-Key:
    $var: credentials.apiKey
  Content-Type: application/json

API Key in Query Parameter

# File: auth/make-api-client.map.yml
baseUri: https://api.example.com/v1
defaultQueryParameters:
  api_key:
    $var: credentials.apiKey
headers:
  Content-Type: application/json

Basic Authentication

# UI Schema
ui:
  schema:
    type: object
    properties:
      username:
        type: string
        title: "Username"
      password:
        type: string
        title: "Password"
        format: password

# make-api-client.map.yml
baseUri: https://api.example.com/v1
headers:
  Authorization:
    $tpl:
      template: "Basic {token}"
      values:
        token:
          $jsonata: $base64encode(credentials.username & ':' & credentials.password)
  Content-Type: application/json

Testing

It's important to implement a test function to verify the credentials work properly:

// File: auth/test.js
exports.test = async function (context) {
  try {
    // Make a simple API request that requires authentication
    const responseData = await context.apiClient.get("/user/profile")
    return responseData.id !== undefined
  } catch (error) {
    return false
  }
}

Best Practices

Security: Never hardcode sensitive information. Use connector parameters or user inputs.
Error Handling: Implement proper error handling in your API client for authentication failures.
Validation: Validate user input before attempting to use it for authentication.
Documentation: Provide clear instructions in the UI about what credentials are needed and where to find them.
Testing: Thoroughly test your authentication implementation with various inputs and edge cases.