Skip to content

API authentication

Authentication and authorization are crucial aspects of securing APIs, ensuring that only authorized users or applications access sensitive data or perform actions. Authentication is the process of confirming a user's identity through credentials like usernames and passwords, while authorization determines the actions and resources a user can access based on their identity and permissions.

Several authentication methods are commonly used by Custom Connectors.

Authentication methods

Matillion supports various authentication methods, each suited to different API requirements, including Basic Authentication, Bearer Token, API Keys, and OAuth. Each of these authentication methods serves distinct purposes and offers varying levels of security and flexibility. Here's a brief overview of each authentication method:

Basic authentication

Basic Authentication is a simple method of API authentication where a client sends a username and password in the HTTP request headers. When employing basic authentication over HTTPS, it's essential to include authentication credentials in each request made to the REST API.

  • How it works: Choose Basic Auth as the Authentication Type from the dropdown, and then provide a username and password. These credentials are then included in the HTTP header of the request for secure authentication.
  • Use cases: Basic Authentication is simple and suitable for scenarios where security requirements are moderate, especially when used in conjunction with HTTPS. It may be appropriate for internal or trusted applications.
  • Example: Authorization: Basic base64EncodedCredentials

Bearer Token authentication

Bearer Token Authentication is a simple and widely used method for securing APIs. In this approach, you need to include a token in the HTTP request headers. The token is typically obtained by authenticating with the API provider, and it serves as proof of authorization.

  • How it works: Choose Bearer Token as the Authentication Type from the dropdown, and then provide a Token value. The token serves as proof of authorization.
  • Use cases: Bearer token authentication is commonly used in RESTful APIs.
  • Example: Authorization: Bearer <token>


An API key is a token that must be supplied when making API requests to secure endpoints. The key is included in the API request as a parameter, header, or part of the URL.

  • How it works: Choose API Key as the Authentication Type from the dropdown.
    • Key name: Enter a unique name for the API key in this field.
    • Key value: Input the actual API key value.
    • Add to: Choose how to transmit the key, either as a "Query Parameter" or a "Header Parameter". - Query parameter: This option appends the API key to the URL in the format GET / - Request header: Alternatively, you can include the API key in the request header like this:
      GET / HTTP/1.1
      `X-API-Key: abcdef12345

      This choice depends on the API's requirements and conventions for handling API keys.


You can create and store OAuth connections across the Custom Connector interface to authenticate data sources using OAuths tab on the Custom Connector dashboard. OAuth connections are used to securely authenticate and authorize access to external services or APIs that you want to integrate with in your Matillion workflows.

Any existing OAuth entries are listed on the OAuths page, oldest first. Click the trashcan button alongside an OAuth entry to delete it, and then click Yes, delete to confirm deletion, or click Never mind if you cancel the deletion process.

The Custom Connector interface provides a mechanism for authenticating with OAuth to access and extract data from API endpoints. To set up OAuth authentication in connectors, you can utilize the Manage OAuth process or you can setup an OAuth using OAuths.

Custom Connector OAuths menu

Read Add OAuth to learn how to create an OAuth profile for use in Custom Connector.