Connecting to an API

Connect to any REST, GraphQL or SOAP API.

You can make requests to any HTTP, GraphQL or SOAP API with Retool. Many developers get data from their own internal APIs, render them in Tables, then post data (like resetting passwords) back again to their own API. But you can also connect Retool to APIs like Stripe, Salesforce, Slack, etc.

You query REST resources in an interface where you can set URL params, headers and cookies:

POSTing to httpbin

📘

Video: connecting your API to Retool

We put together a video that walks through the basics of connecting an API to Retool here.

If you would like to use authentication for a specific API multiple times, you can create a new datasource so the base URL and authentication scheme are saved:

API Authentication

Authorization bearer token

Adding an API that uses a bearer token authentication scheme is easy in Retool. Just add it as a global header in the Resource configuration screen and all your API requests that use the resource will have the right auth headers sent over.

Basic Auth

To enable Basic Auth authentication schemes, choose Basic Auth in the Authentication dropdown and then provide the username and password.

OAuth 2.0

Retool also supports OAuth 2.0 authentication scheme. Unlike the previous examples, authentication details are not shared between your end users unless you enable the "Share OAuth2.0 credentials between users" option.

When the share credentials option is disabled, each of your end users will be required to authenticate via the OAuth authentication flow. The Access/Refresh token that is returned by the OAuth identity provider will be encrypted and then associated with the user's current session with Retool. This allows you to delegate authorization and authentication to the OAuth Identity provider.

Here is a sample configuration of Retool connecting with Google's OAuth 2.0 API. Things to take note of:

  • We added the header: Authorization: Bearer OAUTH2_TOKEN - the OAUTH2_TOKEN is a magic placeholder string that gets replaced with the access token at runtime. You can use this magic string in the header or in the URL parameters of the query.
  • The OAuth Callback URL is static and cannot be changed - you must use this URL and provide it to the OAuth configuration.
  • The Login Test URL is used to test whether or not the user is currently authenticated. Retool will make a GET request to the URL and if the response is not a 20x, it will pop a modal open and ask the user to authenticate against the API.

Retool's Consent Screen

Kicking off an OAuth2 flow will redirect the user to Retool's consent screen, and upon consent, to the Identity Provider's consent screen. If you're running Retool on-premises, you have the ability to disable Retool's consent screen for a particular resource by toggling "Skip Retool consent screen & attempt login".

This is equivalent to sending an authorization request with the ?prompt=none URL parameter set. If this request returns any error (for example, "user interaction required") Retool will fall back to a consent-based flow.

Redirect directly to Identity Provider

📘

The OAUTH2_TOKEN magic string

Pay close attention to how we used the OAUTH2_TOKEN string in the screenshot above! Retool will substitute that string with the OAuth Access Token at runtime. This is how you tell Retool how to use the access token in order to authenticate with your api.

Cookie Based APIs

Retool also supports APIs that use cookies for authentication. In this scenario, the API authorizes a session by responding with a Set-Cookie header that contains an authorization token. The API then expects all future authenticated requests to send that same authorization token in the Cookies header.

Though Retool proxies all HTTP requests through the backend, Retool supports forwarding the cookies set by the API to the user's browser - including attributes such as the expiration date. The cookies are then stored in a HTTPOnly cookie in the user's browser which is tied to the lifecycle of the user's current session. All future requests the user makes to the API will have the same cookie added to their request.

To configure this, simply tell Retool the name of the cookie that should be forwarded onto the user's browser. Just like in the OAuth 2.0 api integration, you can also specify a URL to check the user's authentication status.

After that has been configured, you will need to create a login page in Retool that asks the user for authentication details and then makes an API request to the login endpoint. After a successful login, the authentication cookie will be parsed from the response and forwarded along onto the user's session.

Double cookie submit pattern

The double cookie submit pattern is implementable by using COOKIE_your_csrf_token in the headers like below.

Forwarding cookies that are pre-set on your domain

📘

Only available for on-prem users of Retool

You can automatically forward specific cookies that are pre-set on the domain you are running Retool on. For example, say you have Retool hosted on retool.yourdomain.com and you want to automatically forward cookies named someCookie1 and someCookie2 that are set on the yourdomain.com domain.

First, you'll need to add these cookies to an allow-list with an environment variable. If you want to allow forwarding for multiple cookies, add them as a comma-separated string as below.

FORWARDABLE_SAME_DOMAIN_COOKIES_ALLOWLIST=someCookie1,someCookie2

Next, in the resource settings page for the resource that should forward these cookies, add the cookies in the List of cookies to forward section, as below.

That's it! someCookie1 and someCookie2 will now automatically be forwarded for this resource whenever you make a request. If you want to include one of the cookies in a header, you can follow the COOKIE_someCookie1 pattern described here.

AWS v4 Signature Based Authentication

You can also sign your API Requests using Amazon's v4 Signature Signing Process.To do that, you need to specify your AWS Region, Service Account Key, Secret Key and your AWS Service.

The AWS Service will correspond to the subdomain of your API. For example, if you are making a request to a service hosted at https://xyzabc.execute-api.us-east-1.amazonaws.com, then your service should be xyzabc.execute-api.

JSON Body in API requests

By default, it is easy to construct a JSON object using the key-value interface. To create a more complex structure, you can nest objects as children of a key like below:

Alternatively, you can also switch from the key-value interface to send custom JSON. Here is an equivalent query to above. You will need to specify the Content-Type header in order for this to work.

🚧

Formatting JSON can be a little confusing at first!

For a value that should be a string, make sure to wrap the {{ }} with double quotes.
For a value that is a boolean / number, do not wrap the {{ }} with double quotes.
For a value that is an object / array, wrap the value inside with a JSON.stringify

Since it can be a little confusing at times to discover the right way to format, an easy alternative is to just construct the entire object dynamically like below:

SOAP APIs

SOAP API can be done very similarly. See SOAP APIs

Uploading Files

Retool currently supports two methods for uploading files

  • Uploading a binary file without any metadata
  • Uploading a file using FormData

Here are some quick examples:

The filepicker component

The button will allow you to instruct users to select a file to upload. In the screenshot above, once the file has been selected, uploadFile will be run.

Uploading using binary

Uploading using form data

Misc. features

How do I automatically add user specific information like the user's email or Google ID?

📘

Only available for on-prem users of Retool

If you want the API requests that get made in Retool to contain information about the user who made the request, you can use two magic constants in the API Resource configuration screen.

%USER_PRIMARY_EMAIL%
%USER_GOOGLE_ID%

For example, if you want every api request to contain an extra header called X-User-Email and X-User-Google-Id you can just add two new resource headers like in the screenshot below.

Updated 22 days ago


Connecting to an API


Connect to any REST, GraphQL or SOAP API.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.