Custom connector authentication

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. This guide describes the authentication methods you can choose when creating or editing a custom connector or Flex connector (basic, bearer token, API key, and 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 that represents your bearer token or API key value.

---

​

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.

​

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 , 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 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. To do this, select the radio button for the OAuth connection you want to use in the Test column of the providers list.