Authentication API

This API must be used to receive an access token, giving the third-party application temporary access to the Etlworks APIs.

To access resources (Flows, Connections, etc.) that exist under the tenant, you must authenticate using an account created under the tenant or perform a super admin tenant switch (read below).

Get access token

• PATH: /rest/v1/token-auth/issue.
• EXAMPLE: https://app.etlworks.com/rest/v1/token-auth/issue.
• METHOD: POST.
• REQUEST BODY: {"login": "user", "password": "password"}, where user is the user ID of the Etlworks user and password is the password for that same user.
• REQUEST CONTENT TYPE: application/json.
• RESPONSE: {"token": "access token"}, where access token is an actual access token that will be used for all authenticated requests to the API.
• RESPONSE CODES: 200 for success, 401 and 403 for not authorized, and 500 for an internal error.

Super Admin tenant switch

This only applies to user accounts with Super Admin role.

User accounts withSuper Admin role can temporarily switch tenant in context, in other words pretend to be a user that belongs to a specific tenant. This is useful when you want to make API calls across multiple tenants and don't want to re-authenticate with each tenant specific user account.

Tenant switching is done on the already issued valid access token (see above Get access token).

• PATH: /rest/v1/token-auth/tenants/{tenant_id_to_switch_to}
• EXAMPLE: https://app.etlworks.com/rest/v1/token-auth/tenants/1
• METHOD: POST.
• REQUEST BODY: empty
• REQUEST CONTENT TYPE: application/json.
• RESPONSE: {"token": "access token"}, where access token is a new access token with specified tenant in context.
• RESPONSE CODES: 200 for success, 401 and 403 for not authorized, and 500 for an internal error.

After you received new access token with tenant in context use it instead of the original token when making API calls. You can continue switching tenant in context on the latest token.

In order to remove tenant in context (return back to Super Admin level) make another tenant switch call with {tenant_id_to_switch_to} set to 0.

Two-Factor Authentication workflow

If you have two-factor authentication enabled for the account you are trying to get access token for, then it adds one extra step into the authentication process.

First make regular authentication call to /rest/v1/token-auth/issue endpoint with login and password in the payload, described in Get access token section above. Response however will have tfaToken instead of token, it will be used in the next API call and valid only for the next 2 minutes.

• PATH: /rest/v1/token-auth/issue.
• METHOD: POST.
• REQUEST BODY: {"login": "user", "password": "password"}, where user is the user ID of the Etlworks user and password is the password for that same user.
• REQUEST CONTENT TYPE: application/json.
• RESPONSE: {"tfaToken": "two-factor authentication token"}, where two-factor authentication token is a token that should be sent in the consecutive call.

Second call should be made to the same /rest/v1/token-auth/issue endpoint, but this time payload should contain tfaToken from last step and code which is a code that has to be calculated based on Time-based one-time password (TOTP) algorithm and a secret shared with you during 2FA enabling process. If 2FA is already enabled, secret can be viewed by going to About -> Two-Factor Authentication -> Add new device -> Enter password -> view secret.

• PATH: /rest/v1/token-auth/issue.
• METHOD: POST.
• REQUEST BODY: {"tfaToken": "two-factor authentication token", "code": "TOTP  calculated code"}, where tfaToken comes from last response and code is calculated based on TOTP algorithm (current time and shared secret).
• REQUEST CONTENT TYPE: application/json.
• RESPONSE: {"token": "access token"}, where access token is an actual access token that will be used for all authenticated requests to the API.