Documentation

Welcome to Retool! We're a fast way to build custom internal software.

You'll find the 5 minute demo, quickstart guide, and documentation for each of our connectors and components here. If you've got any questions -- chat with us on the bottom right!

Get Started    Guides

APIs

Connect to any API.

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

You query them in an interface similar to Postman:

`POST`ing to httpbin

POSTing to httpbin

If you need 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.

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

  1. Use the SOAP endpoint as the URL of the request. If you are using WSDL, then you must give the path to the WSDL inside the URL.
  2. SOAP endpoints respond to POST requests, so change the request method to POST
  3. Add the header 'Content-Type' = 'text/xml'
  4. In the body, change the body type to "Raw" and then define the SOAP request.
  5. Consult your API specification for the headers required. The name of the SOAP method is usually specified in the SOAP body, but sometimes it may be specified in the header.
Configuring an example SOAP request.

Configuring an example SOAP request.

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


-->