4.2.2.15.1. HTTP Client Authentication
Most internet services are protected by some level of authentication. In our gateway, you can set up a "Global authentication" (configure it once, and reuse it in multiple calls) or configure your authentication individually per call.
Global Authentication
Global authentication is configured by clicking on this icon:
Use global authentication when you will be interacting with the same system over and over in order to avoid repeating your configuration and having to update or refresh information in each call when updates come up.
Authentication at Call Level
Authentication can also be configured at call level and has exactly the same options only it is run before that individual call and cannot be reused in other calls.
Authentication Types
We support the following authentication types: (Basic, Digest, NTLM, Any, Cert, Form, OAuth 1a, OAuth 2.0 with Bearer, OAuth 2.0 with Credentials). The partner hosting the HTTP server should inform you of the best authentication method to use with their system.
| None | By default, no authentication is set on calls. This will typically be used for public lookup services exposing URIs to "GET" requests. Most substantive API calls, will require some form of authentication however. |
| Basic |
Basic authentication is a straightforward method of authentication where the username and password are sent in Base64 encoding within the - username: username used in the authentication - password: password for above username - preemptive authentication: In a call, preemptive authentication means that the authentication headers are sent directly in the call as opposed to having an initial back and forth between us and the partner's server for authentication. If you don't know what to do with this, leave it unchecked. - trust level:The trust level defines the level of security used in the SSL handshake (default is 'standard').
- Valid HTTP return codes: Comma separated list of expected return Http codes. If the return code is not in the list, the polling throws an error. The default is '200,201,202,204,205'. |
| Digest |
A secure alternative to BASIC authentication that transmits hashed credentials to prevent password exposure. - username: username used in the authentication - password: password for above username - preemptive authentication: In a call, preemptive authentication means that the authentication headers are sent directly in the call as opposed to having an initial back and forth between us and the partner's server for authentication. If you don't know what to do with this, leave it unchecked. - trust level:The trust level defines the level of security used in the SSL handshake (default is 'standard').
- Valid HTTP return code: Comma separated list of expected return Http codes. If the return code is not in the list, the polling throws an error. The default is '200,201,202,204,205'. |
| Any |
"Any" means that we will take the username/password combination and use it in the request without imposing a realm or a port. We adapt to the challenge the target server requires in responding to the request. - username: username used in the authentication - password: password for above username - trust level:The trust level defines the level of security used in the SSL handshake (default is 'standard').
- Valid HTTP return code: Comma separated list of expected return Http codes. If the return code is not in the list, the polling throws an error. The default is '200,201,202,204,205'. |
| NTLM |
A Microsoft-proprietary authentication protocol used for securing connections in Windows-based networks. It supports challenge-response mechanisms for enhanced security. - username: username used in the authentication - password: password for above username - trust level:The trust level defines the level of security used in the SSL handshake (default is 'standard').
- Valid HTTP return code: Comma separated list of expected return Http codes. If the return code is not in the list, the polling throws an error. The default is '200,201,202,204,205'. |
| OAuth 1.0a |
A token-based authentication using signed requests. - OAuth1 Signature Method: Specifies the algorithm used to sign the request. This ensures the integrity and authenticity of the message.
- OAuth1 Consumer Key: A public identifier issued to the client by the OAuth server. It is used to identify the client application making the request.
- OAuth1 Consumer Secret (optional): A secret key shared between the client and the server, used to sign requests in combination with the token secret.
- OAuth1 Token: A temporary or permanent token issued to the client after successful authentication. It represents the user's authorization to access their resources.
- OAuth1 Token Secret (optional): A secret associated with the OAuth1 Token, used to sign requests along with the Consumer Secret.
- OAuth1 Key Alias: An optional alias used to reference your key. This is used if you've required SHA1withRSA signature method.
- OAuth1 Realm (optional): Specifies the protection space (or domain) the credentials apply to. It is often used to group resources requiring authentication under a specific namespace. Typically included in the Authorization header, but its usage is optional and server-specific.
|
| OAuth 2 |
A modern and widely used authorization protocol that separates resource owner credentials from the client app. Select this option to configure a specific OAuth 2.0 flow (such as Authorization Code) directly inside this HTTP Client. Under this option, Babelway retrieves the token and caches it. When the "Access Token Validity Duration" expires, Babelway automatically requests a new token (or refreshes the existing one) before executing the next call. - OAuth2 Provider: Choose "Custom" to manually enter all URLs, or select a preset (e.g., "Google") to automatically fill in the standard endpoints for that provider. - Grant Type: Determines how the Access Token is retrieved. - Application (Client) ID: (Visible for Client Credentials grant) The unique public identifier for your application issued by the OAuth provider. - Client Secret: (Visible for Client Credentials grant) The secret key for your application known only to you and the provider.. - Authorization Code URL: (Visible for Authorization Code grant) The URL where the user is redirected to log in and grant permissions. - Access Token URL: The server endpoint used to exchange the authorization code (or other credentials) for an Access Token. - Access Token Custom HTTP Headers: Click Add to inject specific headers into the token request call (e.g., Accept: application/json). This is required by some rigid API providers. - Refresh Token URL: (Visible for Authorization Code grant) The endpoint used to refresh the Access Token when it expires. If provided, Babelway will attempt to refresh the token automatically based on the validity duration. - Access Token Validity Duration: The time (in seconds) Babelway should consider the token valid. Babelway caches the token for this duration. Once elapsed, it uses the Refresh Token URL to get a new one before the next call. This is best for specific, isolated integrations where you need full control over the OAuth flow parameters (URLs, Scopes, Grants) directly within the HTTP Client step, without creating a shared Connection object. |
| CERT |
Uses client certificates for authentication. The client presents a digital certificate to the server, proving its identity, typically used in secure corporate environments. - Certificate Alias: Alias identifying the key tied to the public certificate you have agreed upon with your partner for the exchange. It allows us to sign the exchange. |
| OAuth 2 Client credentials (Deprecated) |
Refers to OAuth2 flows that authenticate using client credentials, commonly used for machine-to-machine interactions. This option allows you to configure a custom, preliminary HTTP request to fetch an Access Token before the main call is executed. This option lets you define the specific Login URL, headers, and response parsing logic directly within the step. This is ideal for one-off configurations or non-standard OAuth flows. - Login URL: The endpoint URL used to retrieve the token (e.g., https://api.service.com/oauth/token). - HTTP Headers: (Optional) Add headers required specifically for this login request. (e.g., Authorization: Basic [Base64Credentials] if the API requires Basic Auth to fetch the token). - Grant Type: The value for the grant_type parameter sent in the body (e.g., client_credentials or password). - Content-Type: The format used to send the credentials in the body. Typically application/x-www-form-urlencoded or application/json. - Valid HTTP Return Codes: The HTTP status codes that indicate the login was successful (e.g., 200). This is best for standard server-to-server integrations (Salesforce, Microsoft, etc.) where you want to reuse the credentials across multiple channels and have Babelway manage the lifecycle entirely. This is the most robust and recommended flow when supported. |
| OAuth 2 With bearer |
OAuth 2.0 with Bearer tokens, a widely used authorization framework where access tokens are sent in the This mode does not retrieve a token for you. It expects you to provide a valid Access Token string, which Babelway will simply inject into the request header. - Bearer: Bearer token to be added to the header. Babelway does not check if this token is expired. If the token becomes invalid, the HTTP request will normally fail with a 401 error. |
| Implicit OAuth1 token | This feature is only accessible when using Babelway through a Tradeshift App. In that case, your Tradeshift's OAuth1 integration token will be used if available. |
| AWS Signature Version 4 (S3 Only) | This type of authentication allows you to make calls to AWS services. It is currently limited to the S3 service. 4.2.2.15.1.1 AWS Signature Version 4 (S3 Only) |
Tip: Which "Client Credentials" should I use?
When in doubt always use "OAuth 2.0". This is the most modern and robust method. Babelway automatically tracks the token validity. When it expires, the system seamlessly requests a new one (or uses the refresh token) without any manual intervention.
Troubleshooting:
If your OAuth 2 integration is failing, check the following common errors:
HTTP 401 Unauthorized
This error usually indicates that the Access Token is missing, invalid, or expired. If you are using the Manual Bearer mode, double-check that the token string provided in the field hasn't expired. For Client Credentials (Managed or Inline), this often means the Client ID or Secret is incorrect, or the Access Token URL is wrong.
HTTP 403 Forbidden
This suggests the token itself is valid, but the application does not have permission to access the specific resource. This is typically a Scope mismatch. You should verify on your OAuth provider's side that the Client ID associated with the token has been granted the specific roles or scopes required for this API call.