Skip to main content

Generic API key connection

Explore how to configure a generic API key connection.

Generic API key lets you connect to APIs that require authentication with an API token. You can add authentication fields your app requires and dynamically configure URL, URL params and/or HTTP headers with these fields. When an API request using the connection is run, users are prompted to enter their API key (or any additional custom field configured) to connect with your tool.

Base URL​

Base URL is the URL prefix for all API paths in your tool. Typically, a base URL format is https://api.example.com or https://userdomain.example.com. If you are not sure, check in with your tool's API (or developer) documents to get the base URL for your connection.

Tip

Enter base URL in https://api.example.com or https://userdomain.example.com format.

Request parameters​

Setup URL params and Headers here. Use {{auth.field_key}} to insert an authentication field in URL params or Headers.

Authentication fields​

Authentication fields are used to request info from users when trying to authenticate in your app. You can think authentication fields as the variables to establish the connection. Actioner does not provide any field by default. You can add API key and any additional field your app requires for authentication. For example, if you setup email and API token as authentication fields, each user enters their own email and API key to connect.

The values entered by users (their email and API token) are then passed to URL params or Headers depending on the connection configuration. Whenever an API request associated with your connection is sent, the request is authorized with the passed values.

In URL, URL params and/or Headers of your connection, you can reference to an authentication field by {{auth.field_key}}notation. {{auth.field_key}}returns the user-provided value of field_key and that value is appended inside URL, URL params and/or Headers.

Let's say your app requires Email and API token to authenticate. You can add these two authentication fields as below:

Authentication fields for a generic API key connection

When a user tries to connect, they are prompted to enter their email and API token.

Enter credentials for a generic API key connection

Adding an authentication field​

Click + Add field to add any field your tool requires for API key authentication. On the opening screen, fill out the below properties:

Label: Enter the field's friendly name. It is the name visible to users while authenticating.

Key: Enter a unique key, such as api_key. You can add {{auth.api_key}} in URL, URL Params and/or Headers to insert the value of this field.

Field type: Use Text field for most text input, or Password to obscure text for secret values.

Mandatory: Enable, if users are required to enter a value to this field while authenticating.

Placeholder: Enter a text displayed when no value is entered in this field. You can provide a tip to direct users on what info to enter while authenticating.

Helper text: Enter a helper text for additional notes or hints. It is placed as a small note under the field.

Configuring authentication fields​

You can think of authentication fields as the variables of your connection. When a user tries to connect, they are prompted to enter their credentials for authentication. Each time an API request associated with your connection is triggered (when an action that contains an API request with that connection is run), the value of the authentication field becomes the user-provided value. The authentication field referenced inside URL, URL params and/or Headers, is automatically evaluated as the value entered by the user.

Adding an authentication field is not mandatory while configuring a generic connection, especially if you are the only user in your app. However, there are two important benefits of adding authentication fields.

  1. When shared credentials is disabled for a connection, each user enters their own API key to connect. For these scenarios, you can dynamically reference the API key authentication field on your request's URL params or headers.

  2. If you enter the API key directly inside the request's URL params or headers, that API key is exposed to other app admins who have the right to view and edit the configuration of your connection. But when you define it as an API key authentication field, it is kept as obscured text with a secret value.

Configuring generic API key connection​

  1. Add your fields on Authentication fields. Click + Add field to add any field your tool requires for API key authentication. Any field added here will be requested from users while entering credentials. Assume you created an authentication field for API key. Users will be prompted to enter their API key on the credentials screen.

    Tip

    Make sure to setup keys, labels, field types and mandatory attribute properly. These fields will be displayed to users on the entering credentials screen in the order added here.

  2. Enter Base URL.

  3. Under URL Params and Header tabs, click + Add parameter to insert parameters in key:value format. When you want to append an authentication field into URL Params and Header, type {{auth.field_key}}.

    Tip

    When you need other additional fields, add them under Authentication fields.

Generic API key connection with an example​

Let's see how to setup an Airtable connection with API key.

  1. Go to your app's Connections section on App settings tab and add a new connection by selecting Generic API key option.

    Add a new generic API key connection

  2. Enter base URL https://api.airtable.com/v0/apprWpTot9nREO0bM. Replace the app ID with your Airtable app's ID.

  3. Add API key field on Authentication fields‍.

    Enter a friendly name as the label, such as API key.

    Enter a key that does not contain any special characters or space, such as api_key. We will use this key to dynamically insert its user-provided value into the authentication header. In this example, we'll use {{auth.api_key}}.

    You can select password field type.

    Enable mandatory since we'll always require users to provide an API key to be able to connect Airtable successfully.

    You can optionally enter a placeholder and a helper text to hint to users about what information to provide.

    Add API key as authentication field

  1. Go to URL and Request parameters and add below to Headers. Bearer: {{auth.api_key}}

    Tip

    To reference an authentication field URL, URL params or Headers, you can use {{auth.field_key}} notation.

  2. Enter / on test endpoint field and click Save.

    Generic API key connection with Airtable

  1. Click Test connection and enter your API key.

    Test Airtable connection