- 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.
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 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.
admin
and admin
, then:- Base 64 encode
username:password
.admin:admin
will becomeYWRtaW46YWRtaW4=
- 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==
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.
Comments
0 comments
Please sign in to leave a comment.