REST APIs

Connect to any REST API.

You can make requests to any HTTP 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:

`POST`ing to httpbin

POSTing to httpbin

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.

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.

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.

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 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 15 days ago

REST APIs


Connect to any REST API.

Suggested Edits are limited on API Reference Pages

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