Custom API authentication

Retool comes with support for many authentication standards out of the box (See here for more information). However, Retool also has a Custom Auth authentication mode where you can chain together multiple "steps" to support virtually any kind of API authentication. All API Resource authentication methods apply to both REST and GraphQL resources!

🚧

Custom Authentication in Public Apps

Like OAuth 2.0 and other SSO based auth options, custom auth workflows store defined variables using a relation with the authenticating user's Retool account. Because public app viewers do not use a retool account, custom auth is not supported in public apps.

Authenticate using username + password

Suppose your API expects a username-password combination, and returns an authentication token that should be in future requests. You also want each of your users to authenticate individually, so sharing credentials won't work.

1. Creating an empty REST Query resource.

First create a REST Query resource and call it "My Admin API". Click "Create Resource" and navigate back to it in the resource UI.

2. Use "Custom Auth" for your authentication method

Next, at the bottom select "Custom Auth" for your authentication method.

3. Create a "Form (modal)" Step

Click the "Add new step to the auth workflow" button and then choose "Form (modal)" as the step type. By default it will be configured to ask for an email and password.

To see what it looks like, hit "Save" and then click "Test auth workflow" -- you should see a modal appear asking you to enter in some credentials.

Enter in some dummy data, and then submit the form. A debugging interface will appear at the bottom which shows the "scope" of what can be used in following steps. In this case, we'll be using the email and password in an "API Request Step"

4. Creating a "API Request" Step

Create a second step, and this time choose "API Request." Here's where you should configure it to make an API request to your server to obtain an authentication token.

In this case, we'll be pinging the https://httpbin.org/post endpoint which echoes back whatever we send it!

When we save, and press "Test Authentication", we'll see the new scope which includes the response payload from the API request we just made.

📘

Error messages for invalid logins

If a user submits an invalid email and password combo you'll want to alert them that something went wrong. By default, Retool will show the user a notification with a stringified version of the JSON returned by your endpoint if your endpoint returns an error code. If your endpoint does not return a valid JSON, Retool will just display the returned data in the notification. For example, your endpoint could return something like res.status(401).send({ error: 'Invalid username or password' }).

5. Saving the Authentication Token

Let's save the authentication token we got back from the server. To do that create a "Define a variable" step. The "variable name" is a magic string that we can use to refer to the authentication token, and the "value of the variable" is an expression that would interpolate to the authentication token.

In this case, we're defining a "PASSWORD" variable to be the password that was echoed back by the server.

6. Using the saved authentication token

Lastly, we'll pass the defined variable from step 5 as a header. Scroll back up and then configure the Headers section like below:

Make sure to save your final configuration!

7. Using this resource in an app.

There are a few different ways to use a resource with custom auth in app depending on your desired user experience.

Using a login button

Create a new test app, and then create a "Auth Login" component. From there, choose in the "Auth Resource" the API Resource we just set up.

Press the button, and you should be presented with a modal to enter in your credentials. Once that happens, Retool will make the API request you configured earlier and then securely associate the authentication token with your current session.

From here on out, all subsequent API requests will have the authentication header.

Automatically prompt for login using a login verification URL

You also have the option to automatically prompt the user for login to your API. Go to the Resource configuration and scroll to the bottom where you can configure an Auth trigger. Select "Login test URL" and set this to an endpoint that will return a response code in the range 200-299 when the user is authenticated, and a non-2xx status code (e.g. 401 Unauthorized) when the user is not authenticated.

Now if you load a Retool app that connects to this Resource, and you are not yet authenticated to your API, the login prompt will automatically pop up.

Automatically prompt for login using a timeout

In the "Auth trigger" dropdown, you can also select to have the authentication be triggered based on a timeout (in seconds). Your users will then be prompted to login to your resource if they have not logged in within the past X seconds. Note that this value can be either set to a constant number of seconds or it can be set dynamically using a variable from a "Define variable" step.

📘

Run auth automatically

If you set an auth login URL or a login timeout, your users will be prompted with a modal with the option to authenticate to any resources that have custom authentication enabled. If you would like the authentication to be kicked off automatically instead, select the "Run this custom auth workflow without prompting the user" toggle in the resource page.

Refresh auth workflow

If desired, you can configure a set of custom authentication steps that run automatically after any non-200 response when querying a resource. This is useful for refreshing a user's authentication session without them needing to refresh the page.

For example, say that a user has been idle for some period of time and then attempts to query your resource. Their session has expired, so your resource returns a 401 or 403 error code. Instead of returning an error for the query, Retool will first perform the refresh auth workflow you have defined (see image below). If the refresh auth workflow is successful, Retool will attempt to run the failed query again. Because the user will have a valid authentication session after the refresh workflow, the second attempt to run the query will succeed and the user can continue using the app without any interruption.