> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom connector authentication

export const Customconnectors = () => <>the <strong>Custom Connectors</strong> icon <span style={{
  whiteSpace: "nowrap"
}}><img src="/images/global-nav/custom-connectors.png" width="20" height="20" style={{
  verticalAlign: "text-bottom",
  display: "inline",
  margin: "0 1px"
}} /></span></>;

export const designer = "Designer";

export const maia = "Maia";

To fetch data from a REST API using a custom connector, you need to authenticate access to the data source. Authentication ensures that only authorized users or applications can access sensitive data or perform actions.

<Note>
  Your authentication credentials are only used for sending test requests to validate your custom connector configuration. They aren't saved in the custom connector editor.

  The custom connector only saves the authentication type. When configuring your custom connector in Designer, you'll provide your credentials as secrets.
</Note>

This guide describes the authentication methods you can choose when creating or editing a custom connector or Flex connector ([basic](#basic-authentication), [bearer token](#bearer-token), [API key](#api-key), and [OAuth](#oauth)) and explains how to create a custom connector OAuth connection.

When you add a custom connector or Flex connector to an orchestration pipeline in {designer} for the first time, you'll need to provide your authentication credentials when configuring the connector. If you use the bearer token or API key authentication method, you'll need to [create a secret definition](/docs/guides/secrets-and-secret-definitions) that represents your bearer token or API key value.

<Note>
  Hash-based Message Authentication Code (HMAC) authentication is only available for the [Azure Cosmos DB for NoSQL](/docs/components/azure-cosmos-db-for-nosql) Flex connector.
</Note>

***

## Basic authentication

Basic authentication sends your username and password as HTTP request headers. It's suitable for scenarios with moderate security requirements, especially when used in conjunction with HTTPS. It may be appropriate for internal or trusted applications.

To use basic authentication for your custom connector:

1. Find your username and password for the data source.
2. Select **Basic auth** in the **Authentication** tab of the custom connector editor.
3. In **Username**, enter your username.
4. In **Password**, enter your password.

***

## Bearer token

Bearer token authentication sends a token as an HTTP request header. It's commonly used for RESTful APIs.

To use bearer token authentication for your custom connector:

1. Find the value of your bearer token. You can usually get this from the API provider.
2. Select **Bearer token** in the **Authentication** tab of the custom connector editor.
3. In **Token**, enter your token value.

***

## API key

API key authentication sends a key in the API request as a query parameter or header parameter. An API key must be provided when making API requests to secure endpoints.

To use API key authentication for your custom connector:

1. Find the name and value of your API key. You can usually get this from the API provider.
2. Select **API key** in the **Authentication** tab of the custom connector editor.
3. In **Key**, enter the name of your API key.
4. In **Value**, enter the value of your API key.
5. In **Parameter type**, select whether to send the key in the API request as a **Header** parameter or **Query** parameter. This is often specified by the API provider.

***

## OAuth

OAuth connections use an access token as a secure key to communicate with the API provider, which authorizes {maia} to fetch data using the API. The access token often has a specific scope, which determines the data the custom connector will be able to access.

In {maia}, you can create two types of custom connector OAuth connection, which require you to provide corresponding information:

* **Client credentials:** These connections allow the custom connector to authenticate as itself using client credentials and an access token URL. This enables fully automated authentication.
* **Authorization code:** These connections require a user to authorize the custom connector. This enables the connector to access the same resources as the user who authorizes the connection.

For security reasons, access tokens typically expire after a specified period of time. We recommend checking your API provider's token expiration period so that you can re-authorize custom connector OAuth connections when necessary.

<Note>
  Custom connector OAuth connections are used for custom connectors and Flex connectors. They are *not* the same as the OAuth connections used to authenticate other components in {designer}. For information about these OAuth connections, read [OAuth](/docs/guides/oauth).
</Note>

### Prerequisites

To create a custom connector OAuth connection, you'll need the following credentials. To find these, check the API provider's documentation. Client credentials are usually found in the API provider's platform or settings, while the URLs are often standard for all API users.

* Your client ID and client secret for the API provider
* The API provider's access token URL
* For **Authorization code** OAuth connections, the API provider's authorization URL

### Creating a custom connector OAuth connection

To create a new OAuth connection for use in a custom connector:

1. In the left navigation, click <Customconnectors />, then **Custom Connectors OAuth**.
2. Click **Add OAuth**.
3. In **OAuth name**, enter a name for this custom connector OAuth connection.
4. In **Grant type**, select the type of OAuth connection to create:
   * Select **Client credentials** to allow the custom connector to authenticate itself using client credentials.
   * Select **Authorization code** to require a user to authorize the custom connector to access data.
5. In **Client ID**, enter your client ID.
6. In **Client secret**, enter your client secret.
7. For **Authorization code** grant types only, in **Authorization URL**, enter the API provider's authorization URL.
8. (Optional) For **Authorization code** grant types only, expand the **Auth parameters** list to change the parameters included in the authorization request. You can exclude any of the default parameters, and add new parameters.
9. In **Access token URL**, enter the URL used to request an access token from the API provider.
10. (Optional) Expand the **Token parameters** list to change the parameters included in the access token request. You can exclude any of the default parameters, and add new parameters.
11. Click **Authorize**.

### Configuring OAuth authentication

To configure OAuth authentication when creating or editing a custom connector or Flex connector:

1. If necessary, create a custom connector OAuth connection for your API provider as described above.
2. Select **OAuth** in the **Authentication** tab of the custom connector editor.
3. In the **Choose an OAuth provider** drop-down, select the OAuth connection you want to use for this custom connector.
4. Select the checkbox to the left of your chosen OAuth connection.

### Using multiple OAuth connections

You can add more than one OAuth connection to a custom connector. This allows you to use a custom connector to fetch data using different OAuth connections, instead of creating multiple identical custom connectors that use different OAuth connections. Use [variables](/docs/guides/variables) in your orchestration pipelines in {designer} to specify the OAuth connection to use each time you use the custom connector.

To add multiple OAuth connections to a custom connector:

1. Select **OAuth** in the **Authentication** tab of the custom connector editor.
2. In the **Choose an OAuth provider** drop-down, select an OAuth connection to add to this custom connector.
3. Click the **+** icon to add a new row to the providers list.
4. Select another OAuth connection to add. Repeat this process as required. There is no limit on the number of OAuth connections you can add to a custom connector.

To remove an OAuth connection from a custom connector, select the checkbox for the OAuth connection to remove, then click the **-** icon.

If you add multiple OAuth connections to a custom connector, you need to select the OAuth connection to use when [sending a test request](/docs/guides/custom-connector-setup#send-a-test-request). To do this, select the radio button for the OAuth connection you want to use in the **Test** column of the providers list.