API authentication

Retool supports almost any kind of authentication. We've worked with companies to support all standard types of authentication and to create extendible ways to support any home grown authentication we don't natively support.

You can use static authentication tokens or create auth that asks the end user to provide credentials each time they access the application.

This page will teach you how to authenticate your API. If you ever aren't sure how to continue, you can always contact support with the Intercom bubble on this page or the help icon inside the editor.

API authentication

You can add authentication details for an API by navigating to the resources page (or using the modal during onboarding) and scrolling down to the "Authentication" section at the bottom.

This lists all the authentication types we support natively, and "Custom Auth" to create any custom or multi step flows.

Dropdown to add 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 "auth verification endpoint" 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. Similarly, you can use the OAUTH2_ID_TOKEN to substitute for the Oauth ID token when the openid scope is included and sharing OAuth credentials between users is disabled.

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.


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 double cookie submit pattern (COOKIE_someCookie1) described above.

Passing in tokens obtained from your OpenID SSO provider into your API request

If you have setup SSO via OpenID, Retool allows you to use the JWT obtained from the SSO process in your API requests. You can use environment variables that were set up when integrating Retool with your OpenID SSO provider by following the docs 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, and Secret Key.

The AWS Service is an optional field that will be extracted from the base URL if left empty. Normally, the 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.

For AWS v4, you can pass the authentication information in the query params or the Authorization header. By default, the Authenticate using the HTTP Authorization header instead of query parameters option will be checked as many AWS services only support authentication using the header.

Custom and multi step API flows

Do none of the above options work for you? No problem. Check out our docs for custom authentication.