You must use an iClient when authenticating your HTTP connection with OAuth 2.0. You can create an iClient in Resources → iClient or directly in an HTTP OAuth 2.0 connection setup.
When creating an iClient in an application connector, you can toggle between a simple or HTTP view. If multiple connections have the same provider, you can use a single OAuth 2.0 iClient. To create an iClient for a specific API or version, select your application, and the available APIs or versions will appear.
Warning
There are differences between an OAuth 2.0 iClient created in a simple or HTTP-type form view application connector and a universal HTTP connector. The universal HTTP connector will provide the most granularity when creating a connection. Learn more about the differences between a simple application and universal HTTP connector.
iClient resource configuration
Simple iClient application configuration
HTTP iClient configuration
To create an OAuth 2.0 iClient, fill in the required fields:
Fields |
Description |
|
---|---|---|
Client ID |
Enter your client ID as found in your application. |
|
Client secret |
Enter the client secret as found in your application. Multiple layers of protection are in place, including AES 256 encryption, to keep your connection’s secret safe. When editing this form later, you must generate this value again; it is stored only when the connection is saved and never displayed as text. |
|
Grant type |
OAuth 2.0 authentication currently supports four grant types: authorization code, authorization code with PKCE, client credentials, and password credentials.
|
The provided code is obtained by using an authorization server as an intermediary between the client, integrator.io, and resource owner. Selecting Authorization code enables additional required and informational settings.
-
Send client credentials via: Sends a basic auth request in the header or client credentials in the request body.
-
Authorization URL: This is the authorization code retrieval endpoint on the API provider’s authorization server.
-
Redirect URL: Use the callback URL to exchange secure messages with the authorization server after authentication. You must whitelist this URL with your authorization server.
-
Access token URL: integrator.io retrieves the access token from this URL.
-
Revoke token URL: integrator.io makes an HTTP post request to the token revocation endpoint URL to revoke a particular token.
-
Valid domain names: integrator.io validates the HTTP requests sent to various OAuth URLs using the domain name value. If the Authorization URL, access token URL and revoke token URL have different domain names, provide them as comma-separated values in any order.
PKCE, often used for public client applications like mobile or single-page web apps, adds an extra layer of security by requiring the generation of a unique code verifier. This random value is transformed into a code challenge using a cryptographic hash function, protecting your data from code injection and interception attacks. Meanwhile, the Password Credentials grant type simplifies the authentication process for trusted clients and direct user interactions, eliminating the need for additional authorization servers.
-
Code challenge method: Algorithm used for generating code challenge.
-
Send client credentials via: Sends a basic auth request in the header or client credentials in the request body.
-
Authorization URL: This is the authorization code retrieval endpoint on the API provider’s authorization server.
-
Redirect URL: Use the callback URL to exchange secure messages with the authorization server after authentication. You must whitelist this URL with your authorization server.
-
Access token URL: integrator.io retrieves the access token from this URL.
-
Revoke token URL: integrator.io makes an HTTP post request to the token revocation endpoint URL to revoke a particular token.
-
Valid domain names: integrator.io validates the HTTP requests sent to various OAuth URLs using the domain name value. If the Authorization URL, access token URL and revoke token URL have different domain names, provide them as comma-separated values in any order. This field protects your OAuth 2.0 credentials so other users creating connections with the same iClient resource can't point their connection to a nonsecure URL that would receive your client secret.
Limits the authorization scope to the protected resources under the client's control or to those previously arranged with the authorization server. Selecting Client credentials exposes additional required settings.
-
Send client credentials via: Sends a basic auth request in the header or client credentials in the request body.
-
Use JWT: Use JWT (JSON Web Token) as a secure digital pass to improve your app’s identity for OAuth specification. You can generate secure JWT tokens by signing in using signature methods such as RSA-SHA and HMAC-SHA. Then, you can utilize these JWT tokens or access tokens to invoke your APIs securely.
-
Signature method (JWT only): Select the required method to sign the API call. For HMAC signature options, the secret key appears. For all other options, a private key is required.
-
Secret key (HMAC only): Use this key as a secret password that generates the JWT signature.
-
Private key: Copy the private key from the portal you want to use to authenticate the connection. Before you add it to integrator.io, you must replace all newline characters (\n) throughout the private key. The private key must be in PEM format. You can convert PFX certificates or convert from a PPK file.
-
Payload: The JSON object contains the message sent to the application. This is used along with the secret key to ensure no alteration to the message along the way.
-
Header: The JWT header is a JSON object that typically consists of two properties:
-
alg (Algorithm): Specifies the algorithm used to sign the token. It can be HMAC SHA256, RSA SHA256, or others, depending on the chosen cryptographic algorithm.
-
typ (Type): Indicates the token type, typically set to "JWT" for JSON Web Tokens.
-
-
-
Access token URL: integrator.io retrieves the access token from this URL.
-
Revoke token URL: integrator.io makes an HTTP post request to the token revocation endpoint URL to revoke a particular token.
-
Valid domain names: integrator.io validates the HTTP requests sent to various OAuth URLs using the domain name value. If the Authorization URL, access token URL and revoke token URL have different domain names, provide them as comma-separated values in any order. This field protects your OAuth 2.0 credentials so other users creating connections with the same iClient resource can't point their connection to a nonsecure URL that would receive your client secret.
Paste your private key:
-
Paste the private key into a text editor.
-
Find
\n
. -
Delete the
\n
characters and press Enter or Return. Repeat this for each instance of\n
. -
Ensure
-----BEGIN PRIVATE KEY-----
appears before the key, and-----END PRIVATE KEY-----
appears after the key. -
Copy and paste the reformatted private key (including the begin and end declarations) into integrator.io.
Your account username and password are used as authentication. Selecting Password credentials exposes additional required settings.
-
Send client credentials via: Sends a basic auth request in the header or client credentials in the request body.
-
Access token URL: integrator.io retrieves the access token from this URL.
-
Revoke token URL: integrator.io makes an HTTP post request to the token revocation endpoint URL to revoke a particular token.
-
Valid domain names: Enter each unique domain name for the OAuth URLs (Authorization, Access Token, Revoke Token) as comma-separated values. If your domain name is the same for each URL, only provide it once. For example, if your URLs are:
-
https://<AccessTokenURL>.domain.com
-
https://<RevokeTokenURL>.domain1.com
-
https://<AuthorizationURL>.domain2.com
write
domain.com
,domain1.com
,domain2.com
. -
Field |
Description |
---|---|
Override default scope delimiter |
Enter the non-space scope delimiter used by your API provider. |
Override access token HTTP headers |
In some rare cases, it may be necessary to include custom HTTP headers with your API requests. The default content-type header value is |
Override access token request body |
Configure your own access token body in JSON format if it is different from the default access token body. This JSON format is finally converted to the form-urlencoded format on the wire. Default access token body format if 'Client Authentication' set as 'body':
Default access token body format if 'Client Authentication' set as 'header': |
Override path to access token field in the HTTP response body |
Add the path to the access token field in your HTTP response body. For example: |
Override refresh token HTTP headers |
In some cases, it may be necessary to include custom HTTP headers with your token refresh requests. As with the 'body' field, any value from the connection can be referenced using {{{placeholders}}} with a complete path matching the connection field. |
Override refresh token HTTP request body |
Configure your own refresh token body in JSON format if it is different from the default refresh token body. This JSON format is finally converted to the form-urlencoded format on the wire. Default refresh token body format:
|
Override path to refresh token field in the HTTP response body |
Add the path to the refresh token field in your HTTP response body. For example: |
Override revoke token HTTP headers |
In some rare cases, you may need to include custom HTTP headers with your API requests. The default content-type header value is |
Override revoke token HTTP body |
Configure your own revoke body in JSON format if it is different from the default revoke token body. This JSON format is finally converted to the form-urlencoded format on the wire. Default revoke body format: |
Send token via: Select the location where your API expects to find the authentication token
Allows you to specify the header name and authentication scheme to use when constructing the HTTP request.
-
Header name: By default, integrator.io will send all authentication type info in the 'Authorization: ' HTTP header field. If the REST API you are connecting to requires a different HTTP header, use this field to provide an override.
-
Header scheme: Use this field to set the HTTP authorization header scheme value. For example, 'Bearer' would be the scheme value for 'Authorization: Bearer my_secret_api_token'
The authentication token is located in the URL. Specify the query string parameter name that holds the token value.
Parameter name: Use this field to specify the name of the URL parameter that holds the API token value. For example, if you specify myAPITokenURLParam
, then all HTTP requests will include ?myAPITokenURLParam=[token]
Field |
Description |
---|---|
Override HTTP status code for auth errors |
This field only needs to be set if the HTTP status code for auth errors is not 401. For example, an API could return a generic 400 status code instead, and then use a field in the HTTP response body to indicate auth errors. |
Path to auth error field in HTTP response body |
This field only needs to be set if the API returns a field in the HTTP response body to indicate auth errors. For example, if an API returns the field ' |
Auth error values |
Use this field to limit the exact values in the HTTP response body field that should be used to determine auth errors. To provide multiple values, use a comma-separated list. |
Comments
Please sign in to leave a comment.