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

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 also apply to GraphQL!

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", and then scroll down to the very button and hit "Save"

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 step" 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 Authentication" -- 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 echo's 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.

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 echo'd 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.

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.

Custom API Authentication


Suggested Edits are limited on API Reference Pages

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