Important Nexla Help Center Update:
Nexla's Zendesk Help Center pages are being deprecated and will soon no longer be available.
Nexla Documentation is now the home for Nexla's User Guides, with improved formatting and categories that are easier to navigate, providing a better overall user experience.
Please update any bookmarks to the new Nexla Documentation site (docs.nexla.com/user-guides).
_______________________________________________
This article provides instructions for adding API authentication details to new or previously created API credentials in Nexla.
Credentials are created each time a new data source or destination is added to a user's Nexla account. For information about adding data sources and destinations, see articles in the Help Center sections Create a Data Source and Create a Data Flow.
Contents:
1. Introduction
2. Create a New Credential/Open an Existing Credential for Editing
3. No Authentication
4. Basic Authentication
5. OAuth 1.0
5.1 Two-Legged OAuth 1.0
5.2 Three-Legged OAuth 1.0
6. OAuth 2.0
6.1 Two-Legged OAuth 2.0
6.2 Three-Legged OAuth 2.0
7. Token-Based Authentication
8. Credential Validation
9. Advanced Settings
9.1 Additional Request Headers
9.2 Bypass SSL Certificate Validation
9.3 JWT-Based Authorization
9.4 HMAC Signature-Based Authentication
9.5 Requests Signed with Certificates
1. Introduction
APIs provide data communication channels between software applications, and they function based on specified sets of definitions and protocols. Data is transferred to and from applications through APIs using requests and responses with structures determined by these definitions and protocols.
Out of the box, Nexla can connect to any system that uses a REST or GraphQL API. The platform supports many different API authentication mechanisms, including basic, 2- and 3-legged OAuth 1, 2- and 3-legged OAuth 2, and token-based authentication, as well as API connections without authentication.
The following sections provide detailed instructions for adding authentication details to connection credentials in Nexla for each type of API authentication mechanism.
2. Create a New Credential/Open an Existing Credential for Editing
- On the toolbar on the left side of the screen, hover over
, and select
from the dropdown menu to open the Credentials screen.
- Option 1 – Create a New Credential:
- To create a new credential, click
in the top right corner of the screen.
- Select "REST API" from the Credential Type pulldown menu.
- Enter a name for the credential in the Credential Name field.
- Optional: Enter a description of the credential in the Credential Description field.
- Ensure that "Generic REST API" is selected from the API Type pulldown menu.
This option is automatically preselected when setting up a new REST API credential.
- To create a new credential, click
- Option 2 – Edit an Existing Credential:
- To add authentication information to an existing credential, click
on the credential in the list, and select
to open the credential editing screen.
- To add authentication information to an existing credential, click
- Proceed to Section 3 for API endpoints that do not require authentication, Section 4 for basic authentication, Section 5 for 2- or 3-legged OAuth 1.0, Section 6 for 2- or 3-legged OAuth 2.0, or Section 7 for token-based authentication.
3. No Authentication
Many public API endpoints that contain non-sensitive information do not require authentication to access the API's data or functionality. This means that anyone can make requests to the API without providing any credentials, such as an API key or access token.
To set up a credential for an API that does not require authentication in Nexla, follow the steps below.
- Select NONE from the Authentication Type pulldown menu.
Some public APIs that do not require authentication still require hardcoded request headers containing information such as API keys. To set up the credential for public APIs with this requirement, see Section 9 Advanced Settings.
- Proceed to Section 8 to confirm the credential's validity.
4. Basic Authentication
In basic API authentication, a verified username and password is sent with the server request.
To set up an API credential for basic authentication in Nexla, follow the steps below.
- From the Authentication Type pulldown menu, select "Basic".
- Enter the username used to access the API in the Username field.
- In the Password field, enter the password for the username entered in Step 2.
Nexla will create a Base64-encoded string representation of the entered username and password combination, which will be passed in the request headers of the API calls.
- Proceed to Section 8 to confirm the credential's validity.
5. OAuth 1.0
The OAuth 1.0 protocol facilitates secure access to third-party API data without requiring the user to reveal their login credentials. The process involves a series of requests sent between the client application, user, and service provider.
OAuth 1.0 mechanisms are commonly referenced as "two-legged" when the application requests data from users of a third-party service or "three-legged" when authentication occurs between only the application and the server.
To set up an API credential to use OAuth 1.0 in Nexla, follow the steps in Section 5.1 for two-legged OAuth 1.0 or Section 5.2 for three-legged OAuth 1.0.
5.1 Two-Legged OAuth 1.0
- Select OAUTH1 from the Authentication Type pulldown menu.
- Select 2-Legged OAuth1 from the Type of OAuth1 Exchange pulldown menu.
- Select the method that should be used to sign server requests from the Signature Method pulldown menu.
When either HMAC-SHA1 or HMAC-SHA256 is selected, each request signature will be encrypted using the SHA1 or SHA256 algorithm, respectively.
If the API does not require requests to be signed with a dynamic signature algorithm, select PLAINTEXT. - Enter the consumer key for the OAuth 1.0 client in the Consumer Key field.
- Enter the consumer secret for the OAuth 1.0 client in the Consumer Secret field.
- Enter the access token for the OAuth 1.0 client in the Access Token field.
- Enter the access token secret for the OAuth 1.0 client in the Access Token Secret field.
- Optional: If the API requires additional advanced configuration parameters such as the realm, version, etc., enter these parameters in the OAuth1 Advanced Configuration (JSON) field.
Advanced configuration parameters must be entered as a valid JSON object.
- Proceed to Section 8 to confirm the credential's validity.
5.2 Three-Legged OAuth 1.0
- Select OAUTH1 from the Authentication Type pulldown menu.
- Select 3-Legged OAuth1 from the Type of OAuth1 Exchange pulldown menu.
- Enter the request URL that should be used to fetch the request token in the URL for Request Token field.
- Optional: If any optional parameters should be attached to the request URL entered in Step 3, enter these parameters in the (Optional) Request Token URL Parameters field.
Optional request URL parameters should be entered in the form of "key1=value1&key2=value2".
The "oauth_callback" and "oauth_consumer_key" parameters do not need to be included in this field. - Enter the OAuth 1.0 authorization URL used to initial user authorization in the Authorization URL field.
- Optional: If any optional parameters should be attached to the authorization URL entered in Step 5, enter these parameters in the (Optional) Authorization URL Parameters field.
Optional authorization URL parameters should be entered in the form of "key1=value1&key2=value2".
Properties that are autogenerated or are received in previous steps do not need to be included in this field. - Select the method that should be used to sign server requests from the Signature Method pulldown menu.
When either HMAC-SHA1 or HMAC-SHA256 is selected, each request signature will be encrypted using the SHA1 or SHA256 algorithm, respectively.
If the API does not require requests to be signed with a dynamic signature algorithm, select PLAINTEXT. - Enter the consumer key for the OAuth1.0 client in the Consumer Key field.
- Enter the consumer secret for the OAuth1.0 client in the Consumer Secret field.
- Optional: If the API requires additional advanced configuration parameters such as the realm, version, etc., enter these parameters in the OAuth1 Advanced Configuration (JSON) field.
Advanced configuration parameters must be entered as a valid JSON object.
- Click
to authorize the client service via the UI.
- Proceed to Section 8 to confirm the credential's validity.
6. OAuth 2.0
The OAuth 2.0 protocol enables an application to securely access API data on behalf of the user by obtaining an access token, which is then used to authenticate future requests. Specific processes used to access data through OAuth 2.0 vary depending on the API service provider but typically involve a series of requests and token exchanges between the client application, user, and API.
OAuth 2.0 mechanisms are commonly referenced as "two-legged" when the application requests data from users of a third-party service or "three-legged" when authentication occurs between only the application and the server.
- In the developer portal of the service with which Nexla will be integrated, create a new application.
- Obtain the client ID and client secret provided by the service.
Copying the client ID and client secret and pasting them into a Notepad document or other easily accessible location for reference is recommended.
- Add the redirect URL https://<your-nexla-ui-url>.nexla.io/oauth2Auth, where "<your-nexla-ui-url>" is replaced with the root URL used to access Nexla, to the client service.
For customers using the standard Nexla URL, the redirect URL will be "https://dataops.nexla.io/oauth2Auth".
For customers using a rebranded URL or private Nexla install, replace "<your-nexla-ui-url>" in "https://<your-nexla-ui-url>.nexla.io/oauth2Auth" with the root URL used to access Nexla in a browser.
- To continue setting up an API credential to use OAuth 2.0 in Nexla, follow the steps in Section 6.1 for two-legged OAuth 2.0 or Section 6.2 for three-legged OAuth 2.0.
6.1 Two-Legged OAuth 2.0
- Select OAUTH2 from the Authentication Type pulldown menu.
- Select 2-Legged OAuth2 from the Type of OAuth2 Exchange pulldown menu.
- Enter the client ID for the OAuth 2.0 client in the Client ID field.
- Enter the client secret for the OAuth 2.0 client in the Client Secret field.
- Enter the URL that should be used to fetch a token from the API token server in the Access Token URL field.
- Enter the token type that should be used when attaching the OAuth 2.0 token to the request in the Token Type field.
The token type field is automatically pre-filled with "Bearer", and this setting should typically be left to indicate a bearer token. However, if the API vendor uses a different name or case, replace the entry in this field with that information.
- Select the request method that should be used for the OAuth 2.0 token URL from the Access Token URL Method pulldown menu.
Typically, this is set to "POST".
- Select the mode in which the OAuth 2.0 client ID and client secret should be sent with the token URL from the Authentication Payload Mode pulldown menu.
- Encoded Header - In this mode, the client ID and client secret will be Base64-encoded and attached to the authentication header in the request.
- Form Data - In this mode, the client ID and client secret will be attached to the request as form data payload parameters.
- Query Parameters - In this mode, the client ID and client secret will be attached to the token query as query parameters.
- Optional: Nexla automatically includes standard OAuth 2.0 token URL payload properties such as grant_type, client_id, and client_secret in the token request body. If the API requires additional custom payload properties to be sent with the token URL request, enter these properties in the OAuth2: Token Request Body field.
Custom properties must be entered in the form of a JSON dictionary.
- Optional: If additional scopes should be added to the OAuth token calls for this API, enter those scopes in the (Optional) API Scopes field.
API scopes should be entered as space-separated values, i.e., "scope1 scope2 scope3". Nexla will automatically attach these scopes to the request as scope payload properties.
- If the access tokens for this API are short-lived and Nexla should automatically continuously refresh the token to retain a valid access token, check the box next to
.
- Enter the OAuth 2.0 token refresh URL that should be used to fetch a new access token using the current access token and refresh token in the Refresh Token URL field that appears.
This is usually the same as the OAuth 2.0 Token URL.
- Enter the OAuth 2.0 token refresh URL that should be used to fetch a new access token using the current access token and refresh token in the Refresh Token URL field that appears.
- Proceed to Section 8 to confirm the credential's validity.
6.2 Three-Legged OAuth 2.0
- Select OAUTH2 from the Authentication Type pulldown menu.
- Select 3-Legged OAuth2 from the Type of OAuth2 Exchange pulldown menu.
- Enter the client ID used for the OAuth 2.0 client in the Client ID field.
- Enter the client secret for the OAuth 2.0 client in the Client Secret field.
- Enter the URL used to initiate user authorization in the Authorization URL field.
Example authorization URL: https://id.planday.com/connect/authorize
- Optional: If the API requires any additional parameters to be attached to the authorization URL, enter these parameters in the (Optional) Authorization Parameters field.
Additional parameters should be entered in the form of "key1=value1&key2=value2", e.g., "scope=openid offline_access employee:read&state=xyzABC123".
Properties such as client_id, grant_type, and client_secret do not need to be included. - Enter the URL that should be used to fetch a token from the API token server in the Access Token URL field.
Example token URL: https://id.planday.com/connect/token
- Optional: If the API requires additional parameters to be attached to the authorization URL, enter these parameters in the (Optional) Access Token URL Parameters field.
Additional parameters should be entered in the form of "key1=value1&key2=value2".
Properties such as client_id, grant_type, and client_secret do not need to be included. - Select the request method that should be used for the OAuth 2.0 token URL from the Access Token URL Method pulldown menu.
Typically, this is set to "POST".
- From the Authentication Payload Mode pulldown menu, select the mode that should be used to send the OAuth 2.0 client ID and client secret with the token URL.
- Encoded Header - In this mode, the client ID and client secret will be Base64-encoded and attached to the authentication header in the request.
- Form Data - In this mode, the client ID and client secret will be attached to the request as form data payload parameters.
- Query Parameters - In this mode, the client ID and client secret will be attached to the token query as query parameters.
- Enter the token type that should be used when attaching the OAuth 2.0 token to the request in the Token Type field.
The token type field is automatically pre-filled with "Bearer", and this setting should typically be left to indicate a bearer token. However, if the API vendor uses a different name or case, replace the entry in this field with that information.
- Optional: If additional scopes should be added to the OAuth token calls for this API, enter those scopes in the (Optional) API Scopes field.
API scopes should be entered as space-separated values, i.e., "scope1 scope2 scope3". Nexla will automatically attach these scopes to the request as scope payload properties.
- Optional: If the access tokens for this API are short-lived and Nexla should automatically continuously refresh the token to retain a valid access token, check the box next to
.
- Enter the OAuth 2.0 token refresh URL that should be used to fetch a new access token using the current access token and refresh token in the Refresh Token URL field that appears.
This is usually the same as the OAuth 2.0 Token URL.
- Enter the OAuth 2.0 token refresh URL that should be used to fetch a new access token using the current access token and refresh token in the Refresh Token URL field that appears.
- Click
to authorize the client service via the UI.
- Proceed to Section 8 to confirm the credential's validity.
7. Token-Based Authentication
Token-based authentication (TBA) is a popular REST API security method. In this method, a token is generated and sent to the client application during the initial authentication process. The client application then includes this token in subsequent requests to the server to prove identity.
To set up an API credential to use token-based authentication in Nexla, follow the steps below.
- Select TOKEN from the Authentication Type pulldown menu.
- Enter the username used for the API in the Username field.
- Enter the password associated with the username entered in Step 2 in the Password field.
Nexla will generate a Base64-encoded string representation of the username and password combination. This Base64-encoded string will be passed in the request headers of API calls.
- Enter the URL that should be used to fetch a token from the API token server in the Fetch Token URL: URL to Get Token field.
- Select the request method that should be used for the token URL from the Fetch Token URL: HTTP Method pulldown menu.
Typically, this is set to "POST".
- Optional: If the token URL requires authentication information such as the username and password to be sent in the header when requesting a token, enter the name of the request header in the Fetch Token URL: Header Name for User/Pwd field.
- Optional: If the token URL requires a payload to be sent when fetching a token, enter the request body in the Fetch Token URL: Request Body field.
The request body must be entered in valid JSON-object format.
- Select the response format that should be used for the token URL request from the Fetch Token URL: Response Format pulldown menu.
- Enter the path of the token property within the response in the Fetch Token URL Response: Path to Token field.
The path should be entered as a valid JSON path or XPath, depending on the response format selected in Step 8.
- Select whether the generated token should be included in the request header or as a URL parameter in subsequent requests from the Where to Add Token on API Requests pulldown menu.
- When HEADER is selected:
- Enter the header name that should be used to send the token in the Header Name for Token in API Requests field.
- Optional: If a prefix should be prepended to the header value, enter the prefix in the Header Prefix for Token in API Requests field.
The token type field is automatically pre-filled with "Bearer", and this setting should typically be left to indicate a bearer token. However, if the API vendor uses a different name or case, replace the entry in this field with that information.
- Enter the header name that should be used to send the token in the Header Name for Token in API Requests field.
- When URL_PARAMETER is selected:
- Enter the URL parameter name that should be used to send the token as a URL parameter in the URL Parameter for Token in API Requests field.
- Enter the URL parameter name that should be used to send the token as a URL parameter in the URL Parameter for Token in API Requests field.
- When HEADER is selected:
- Proceed to Section 8 to confirm the credential's validity.
8. Credential Validation
To confirm whether or not the selected authentication mechanism works satisfactorily based on the information entered in the corresponding section above, follow the steps in this section.
- In the Credential Validation: URL field, enter a URL from the API vendor that should be used to check whether or not the authentication mechanism works with the information entered in the above sections.
This URL does not need to be the URL of the final endpoint that will be used to read and/or write data.
The validation URL should be one that does not incur a noticeable response delay from the API server, i.e., an endpoint that does not trigger long computations. For example, an endpoint that provides user information or metadata is ideal. Alternatively, an endpoint that fetches a small set of valid records, such as one that fetches a single order item, can also be used.
To bypass credential validation, enter any public endpoint. - Select the API method that should be used to execute the credential validation URL entered in Step 2 from the Credential Validation: API Method pulldown menu, and follow the corresponding instructions below.
Typically, "GET" should be selected for record fetching.
- When GET is selected:
- Select the type of content that will be returned from the credential validation URL from the Credential Validation: Content Type pulldown menu.
- Select the type of content that will be returned from the credential validation URL from the Credential Validation: Content Type pulldown menu.
- When POST is selected:
- Optional: If the credential validation URL requires a payload, enter the request body as a valid JSON object in the Credential Validation: Request Body field.
- Select the type of content that will be sent from the Credential Validation: Content Type pulldown menu.
- Optional: If the credential validation URL requires a payload, enter the request body as a valid JSON object in the Credential Validation: Request Body field.
- When GET is selected:
- Optional: To configure advanced settings for this credential, see Section 9 before completing Step 4 below.
- Once all of the required information has been entered, click
in the upper right corner of the screen to save the credential settings.
9. Advanced Settings
Nexla supports several advanced settings that can be used to authorize requests, including sending additional request headers, using JWT authentication, using HMAC signature-based authentication, and signing requests with certificates. Subsections 9.1-9.5 provide instructions for configuring the API credential to use each of the available advanced setting options.
- Click
at the bottom of the credential editing screen to access advanced settings options for the selected credential.
9.1 Additional Request Headers
- If the API requires any additional request headers to be sent as part of every request, enter these headers in the Headers field.
Additional request headers must be entered as comma-separated values, i.e., "header1:value1,header2:value2".
9.2 Bypass SSL Certificate Validation
- To allow insecure SSL server connections facilitated by bypassing SSL certificate validation at the API endpoint, check the box next to
.
This option only needs to be enabled if the API vendor's SSL certificate has expired.
9.3 JWT-Based Authorization
- If the API vendor requires JWT-based authorization as an additional security layer, check the box next to
, and complete configuration Steps 2-15 below.
For example, an API vendor that uses OAuth authentication might use an additional JWT assertion as part of the OAuth specification.
- Enter the token URL that should be called to initiate JWT authentication in the JWT: Token URL field.
- Enter the request body that should be used for the JWT token URL as a valid JSON object.
The macro "{token}" can be used to dynamically substitute the JWT value.
- Select the content type of the JWT token URL from the JWT: Token URL Content Type pulldown menu.
Typically, the content type is "application/x-www-form-urlencoded".
- Select the format of the response that will be received after the JWT token URL request from the JWT: Token Response Format pulldown menu.
Typically, the response format is JSON or XML.
- Enter the path of the token property within the response as a valid JSON or XPath input, depending on the JWT token response format selected in Step 5, in the JWT: Path to Token field.
- Enter the path to the token-type property within the response as a valid JSON or XPath input, depending on the JWT token response format selected in Step 5, in the JWT: Path to Token Type field.
- Select whether the generated JWT token should be included in the header or as a URL parameter in subsequent requests from the JWT: Token Include Mode pulldown menu.
- When "URL_PARAMETER" is selected as the token include mode:
- Enter the URL parameter name that should be used to send the JWT token in the JWT: Token URL Parameter field.
- Enter the URL parameter name that should be used to send the JWT token in the JWT: Token URL Parameter field.
- When "HEADER" is selected as the token include mode:
- Enter the request header name that should be used to send the JWT token in the JWT: Token Header Name field.
- Optional: If a prefix should be appended to the header value, enter the prefix in the JWT: Token Header Type Prefix field.
- Enter the request header name that should be used to send the JWT token in the JWT: Token Header Name field.
- When "URL_PARAMETER" is selected as the token include mode:
- Enter the time span in seconds over which the JWT token is valid in the JWT: Token Expiration Duration (Sec) field.
- Optional: If a secret key should be used to sign the JWT request and payload, enter the secret key in the JWT: Token Secret field.
- Select the algorithm that should be used to generate the JWT token signature from the JWT: Signature Algorithm pulldown menu.
Typically, the JWT signature algorithm is "HS256".
- Enter the value of the scope claim used for token generation in the JWT: Scope Claim field.
- Enter the value of the audience claim used for token generation in the JWT: Audience Claim field.
- Enter the value of the issuer claim used for token generation in the JWT: Issuer Claim field.
- Optional: If extra claims must be verified in addition to the scope, audience, and issuer claims entered in Steps 12-14, enter these additional claims in the JWT: Extra Claims field as a valid JSON object.
9.4 HMAC Signature-Based Authentication
- If the API vendor requires requests to be signed with a signature generated using a custom HMAC algorithm, check the box next to
, and complete configuration Steps 2-4 below.
- Enter the API key that should be used to sign requests in the HMAC: API Key field.
This API key is provided by the API vendor.
- Optional: If the API vendor also requires an API secret to be used for HMAC signature authentication, enter the API secret in the HMAC: API Secret field.
This is often required, but see the API vendor's documentation for more information.
- Enter the signature generator function that should be used to generate the appropriate signature for each request in the HMAC: Signature Generator Function field.
Nexla currently supports the Base64-Encoded Scala function for HMAC signature generation. Please contact your Nexla Account Manager if assistance with this input is needed.
9.5 Requests Signed with Certificates
- If the API vendor requires requests to be signed with a shared certificate, check the box next to
, and complete configuration Steps 2-3 below.
- Enter the content of the P12-formatted certificate file that should be used to sign the API requests in the Client Certificate in P12 Format field.
The P12-formatted certificate file typically consists of the private key and certificate chain. The file can be opened with any text editor to copy its content, and the content can then be pasted into this field.
- Enter the passphrase associated with the P12-formatted certificate file in the P12 Passphrase field.
Comments
0 comments
Please sign in to leave a comment.