How-to Guide - API Key Authentication

API key authentication is an authentication method that traditionally asks users to generate API keys in the application that they want to connect to. This API key may be scoped to the permissions of the user generating them or permissions could be configured on a key by key basis.

There are a variety of ways in which an API may expect to receive an API key. Common examples include:

• Adding them in the URL parameters of each request (GET www.api.com/resource?api-key=XXX)
• Adding them in the headers of each request (X-API-KEY: XXX)
• Adding them to the username or password field of each request (-u XXX or -u :XXX)

Sample Connector - Iterable

{
  title: 'Iterable',

  connection: {
    fields: [
      {
        name: 'api_key',
        label: 'API key',
        control_type: 'password',
        optional: false,
        hint: 'Get your <b>standard</b> API key <a href="https://app.' \
        'iterable.com/settings/apiKeys" target="_blank">here</a>.'
      }
    ],

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        headers(api_key: connection['api_key'])
      end
    },

    base_uri: lambda do |connection|
      'https://api.iterable.com'
    end
  },

  test: lambda do |connection|
    get('/api/channels')
  end,

  #More connector code here
}

• Check out the full connector code here (opens new window)
• Check out the Iterable API (opens new window)

Step 1 - Defining Connection fields

This component tells Workato what fields to show to a user trying to establish a connection. In the case of API key authentication, you would need the API key that the user has generated in Iterable.

Information from User	Description
api key	The api key generated by the end user for Workato.

This is done in the fields key, which accepts an array of hashes. Each hash in this array corresponds to a separate input field.

    fields: [
      {
        name: 'api_key',
        label: 'API key',
        control_type: 'password',
        optional: false,
        hint: 'Get your <b>standard</b> API key <a href="https://app.' \
        'iterable.com/settings/apiKeys" target="_blank">here</a>.'
      }
    ],

TIP

When defining fields, you need to at least provide the name key. Additional attributes like optional, hint and control_type allow you to customize other aspects of these fields. For sensitive information like Client Secrets, remember to use the control_type as password.

To know more about how to define input fields in Workato, click here.

Step 2 - Defining authorization

This component tells Workato what to do with the values received from the input fields to establish a connection. This is handled through your authorization key. In this key, you begin by first defining the type of authorization. For API Key authentication, you should use api_key.

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        headers(api_key: connection['api_key'])
      end
    },

Step 3 - Applying the credentials to subsequent HTTP requests

Next, you need to tell Workato how to make use of the API key you expect to receive from a user of this connector. This is done in the apply key where you can reference the API Key collected through the connection argument. Any instructions you introduce in the apply key are subsequently applied to all HTTP requests this connector sends after connection is established.

In this example, we have defined the API key we received (connection['api_key']) to be added to the headers of any request. For every HTTP request sent, the headers will contain api_key: XXX where XXX is the API key.

Step 4 - Setting the API's base URI

This component tells Workato what the base URL of the API is. This key is optional but allows you to provide only relative paths in the rest of your connector when defining HTTP requests. Learn how to configure your base_uri here.

    base_uri: lambda do |connection|
      "https://api.iterable.com"
    end

TIP

This lambda function also has access to the connection argument. This is especially useful if the base URI of the API might change based on the user's instance. The connection argument can be accessed in the following format:

    base_uri: lambda do |connection|
      #some code here
    end

Step 5 - Testing the connection

Now that we have defined the fields we need to collect from an end user and what to do with the inputs from those fields, we now need a way to test this connection. This is handled in the test key.

    test: lambda do |connection|
      get('/api/channels')
    end,

In this key, you need to provide an endpoint that allows us to send a sample request using the new credentials we just received. If we receive a 200 OK HTTP response, we show the connection as Successful. In the example above, we are sending a GET request to the /api/channels endpoint and expecting a 200 response if the API key is valid.

Variations

In cases when you need to send the API keys in the URL parameters or User fields in each request, you simply need to modify your apply key.

API key in URL parameters

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        params(api_key: connection['api_key']) # For URL parameters
      end
    },

API key in Username field

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        user(connection['api_key']) # For username
        password("") # user method needs to be accompanied with an empty password declaration.
      end
    },

Connections SDK reference

To be more familiar with the available keys within the connection key and their parameters, check out our SDK reference.