Call user-defined API

Startup
Business
Enterprise
On-Premise
Add-on

Authentication

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 https://etlworks_base_url/rest/v1/httplistener/url_pattern.

Example: https://app.etlworks.com/rest/v1/httplistener/patients

Read about the URL Pattern set for the Listener.

JWT Authentication

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 Auth Location.

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: ?Authorization=Bearer%20access-token.

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.

Basic Authentication

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 Auth Location.

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.

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 Basic and Auth Location 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.

For example, if your user account name and password are admin and admin, then:

Base 64 encode username:password. admin:admin will become YWRtaW46YWRtaW4=
Create standard Basic auth string by concatenating "Basic " and result from step 1. You will get Basic YWRtaW46YWRtaW4=
Base 64 encode the result of step 2. You will get QmFzaWMgWVdSdGFXNDZZV1J0YVc0PQ==
Add string obtained in step 3 to the end of the URL Pattern in the listener. Example: some/example/path/QmFzaWMgWVdSdGFXNDZZV1J0YVc0PQ==. Alternatively, you can add a PATH parameter to the URL Pattern: some/example/path/{auth} . In both cases, you will need to wait one minute before the URL will become available.
Now you can use it as the last path parameter in the URL: /some/example/path/QmFzaWMgWVdSdGFXNDZZV1J0YVc0PQ==