Retool API authentication

Learn how to authenticate Retool API requests.

Available on:Enterprise plan

Beta

The Retool API is currently in beta. Reach out to your Retool account team to get access.

The Retool API uses access tokens to authenticate requests. Organization admins can create access tokens from their organization's Settings > API page.

Create an access token

Retool API availability

The Retool API is available as an opt-in beta for organizations on the Enterprise plan running on Retool Cloud or self-hosted versions 3.18.0 and later. Book a call to learn more.

1. Go to Settings > API and click Create new to generate an access token.
2. Enter a name and description, then select the required scopes.
3. Copy and save your token, as you can only access it once.

You can create access tokens in the API settings for your organization.

Specify scopes and permissions

When you create an access token, you specify scopes that determine its level of access. Each scope has a set of permissions to control what operations are allowed when using the token.

Some scopes support individual read and write permissions. Write access also grants Read access.

Scope availability

Not all scopes may yet be available for your organization.

Scope	Level	Description
Source Control	Read	Grants access to read Source control data with the Retool API.
Source Control	Write	Grants access to write Source control data with the Retool API.
Users	Read	Grants access to read Users data with the Retool API.
Users	Write	Grants access to write Users data with the Retool API.
Groups	Read	Grants access to read Groups data with the Retool API.
Groups	Write	Grants access to write Groups data with the Retool API.
Folders	Read	Grants access to read Folders data with the Retool API.
Folders	Write	Grants access to write Folders data with the Retool API.
Permissions	Read	Grants access to read Permissions data with the Retool API.
Permissions	Write	Grants access to write Permissions data with the Retool API.
App Themes	Read	Grants access to read App Themes data with the Retool API.
App Themes	Write	Grants access to write App Themes data with the Retool API.

Authenticate requests

Authentication is performed using Bearer HTTP authentication with the provided token.

curl -X POST https://retool.example.com/api/v2/apps -H 'Authorization: Bearer $BEARER_TOKEN'

API rate limits

Retool uses a point system for rate limiting where endpoint requests cost a certain number of points. You can use up to 300 points in a 60 second window. If you exceed this, Retool blocks API calls for 60 seconds.

Endpoints	Points
Apps, Folders, Users	2
Access Request, App Themes, Environment, Groups, Resources, Resource Configurations, Source Control, Spaces, SSO, User Attributes, User Invite	5
Permissions	10