Any API built-in the Etlworks Integrator requires authentication, using either a JWT token received from the authentication API or a username and password.
User-defined API endpoint
The endpoint URL is defined as
Read about the URL Pattern set for the Listener.
To configure an API endpoint with JWT authentication, select
JWT when defining the
Auth Type parameter for the HTTP Listener. Select either header (recommended and more secure) or query parameter (less secure) for the
Learn about the Authentication API.
Call Etlworks Integrator's REST API endpoints when using JWT authentication
Step 1. Create an API user.
You can actually use any user, as long as they have a required role (see below). API user can only be used to executed API endpoints created in the Etlworks Integrator using Listeners.
Step 2. Use the user to call an Etlworks Integrator authentication endpoint and receive an access token.
Optionally, you can generate the not-expirable API key and use it as an access token in step 3. In this case, you can skip step 2 altogether.
Step 3. Use the access token received in Step 2 to call Etlworks Integrator API endpoints. The access token must be submitted as a header parameter, as in:
Authorization:Bearer access-token, or query parameter, as in:
Access tokens in the Etlworks Integrator are short-lived and self-expiring. An access token gives you access to the APIs for approximately 10 minutes. It is recommended that you refresh the access token before each call to the API. Alternatively, you can use the not-expiable API key as an access token.
Generally speaking, basic authentication is less secure than JWT. Use it only if it is impossible to use two-step authentication. For example, this would be used when a third-party application has a simple webhook that sends a payload to the API.
To configure an API endpoint with
Basic authentication, select
Basic when defining the
Auth Type parameter for the HTTP Listener. Select either header (recommended and more secure), or query parameter (less secure) for the
Call Etlworks Integrator's REST API endpoints when using basic authentication
Only APIs created in the Etlworks Integrator using Listener can be configured to be authenticated with the basic authentication. All internal Etlworks Integrator's APIs require JWT authentication.
Step 1. Create an API user.
You can actually use any user, as long as they have a role that can execute Flows.
Step 2. Use the username and password for the user created in Step 1 to call an API endpoint.
Read more about basic authentication.
Using static URL for authentication
One of the typical use-cases for user-defined API is integration with third-party webhooks. For example, you can create an API in Etlworks Integrator which will trigger a flow when something happened in a third-party system. You could then configure a webhook in that system so it would call a user-defined API created in Etlworks Integrator.
Many third-party services, for example eBay, implement a webhook system that does not allow configuring the callback URL with query parameters such as
?parameter=value, and does not support header parameters so you won't be able to configure a listener with authentication parameters sent in the header or query parameters.
Here is a simple workaround: listener's
Auth Type should be set to
Query Parameter. Authentication string should be set as the last path parameter and it should be base 64 encoded like a standard Basic auth string.
- Base 64 encode
- Create standard Basic auth string by concatenating "Basic " and result from step 1. You will get
- Base 64 encode the result of step 2. You will get
- Now you can use it as the last path parameter in the URL:
Call user-defined API from Etlworks Integrator
Typically, the third-party application will be calling a user-defined API.
To execute a Flow without leaving the Etlworks Integrator, you will need to create another Flow as a sender, as explained in this article.
Read how to call user-defined PULL API endpoint from the Etlworks Explorer.