Resource authentication

Learn about supported authentication methods for resources.

Retool supports a number of authentication methods for authorizing connections to your data sources. As you create a new resource, you can select one of the methods available and provide the necessary credentials.

API keys and tokens

Certain integrations may require you to provide additional credentials with an API key or token, such as a user ID.

Authentication is performed using an API key or token. You must be able to obtain and provide these credentials to create the resource.

Example credentials

API Key: 1234567890abcdef1234567890abcdef

Auth0

Authentication is performed using an Auth0 client application. You must create this application and then provide the details.

Credential	Description
Domain	The domain URL.
Client ID	The client ID.
Client secret	The client secret.
Audience	The audience URL (optional).

Example credentials

Domain: your-app.auth0.com
Client ID: eKf3N2Bsdke3N5Bjf7JsK2dne
Client Secret: 8e2b1f5d3a4c7b9e1f6d5c3a7b8e9f4d

AWS security credentials

Authentication is performed using the provided AWS security credentials. You must be able to obtain and provide these credentials to create the resource.

Example credentials

AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Region: us-west-2
Role ARN: arn:aws:iam::123456789012:role/SampleRole

Basic

Authentication is performed using Basic HTTP authentication with a username and password. You must be able to obtain and provide these credentials to create the resource.

Example credentials

Username: sampleUser
Password: samplePass123

Bearer

Authentication is performed using Bearer HTTP authentication with a token. Retool automatically includes the Authorization header when interacting with the resource.

Example credentials

Bearer Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.y5T-dGVzZKjT6xZc2Z-s_hN5e_BjWe_u6nZ1P3Alw

Digest

Authentication is performed using Digest HTTP authentication with a username and password. You must be able to obtain and provide these credentials to create the resource.

Example credentials

Username: sampleUser
Password: samplePass123

Google service account

Authenticate with a service account tied to a Google Cloud project. This method allows users to give Retool access to certain APIs or data with the service account's email address.

Retool recommends using service account authentication when you need to share credentials across users but limit Retool's access to a subset of data. This authentication flow restricts Retool's access to APIs or data shared with the service account email address only.

Refer to Google's service account documentation to learn more.

Example credentials

{
  "type": "service_account",
  "project_id": "sample-project-id",
  "private_key_id": "abcd1234efgh5678ijkl9012mnop3456qrst7890",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQChK.......\n-----END PRIVATE KEY-----\n",
  "client_email": "sample-account@sample-project.iam.gserviceaccount.com",
  "client_id": "12345678901234567890",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/sample-account%40sample-project.iam.gserviceaccount.com"
}

OAuth 1.0

Authentication is performed using an OAuth 1.0 client application. You must create this application and then provide the details.

Credential	Description
Consumer key	The consumer key with which to authenticate.
Consumer secret	The consumer secret with which to authenticate.
Access token	The access token with which to authenticate.
Token secret	The access token secret.
Realm	The realm to use.
Signature method	The signature method to use. Either HMAC-SHA1, HMAC-SHA256, or PLAINTEXT.

Example credentials

Consumer Key: xvz1evFS4wEEPTGEFPHBog
Consumer Secret: L8qq9PZyRg6ieKGEKhZolGC0vJZ3Q1z0a4B6A8Zw
Access Token: 370773112-tk5k8d2gOUH2KB8f75xzG3Vr9P9fNrA3nURFPb11
Token Secret: kYjzVBB8Y0mklWf8bFS1C9Ln4J4reF9nnJj6lfF5

OAuth 2.0

Authentication is performed using OAuth 2.0. Your users are redirected to sign in and authorize Retool to access data.

Some integrations, such as Google Sheets, include an option to share user credentials across an organization, allowing all users to interact with the resource as the user. This is known as shared user credentials.

Per-user credentials

OAuth-based authentication with individual user credentials. Each user is prompted to authenticate with Google using an OAuth flow, and API calls from Retool are made on behalf of the logged-in user. When using apps built using authenticated Google resources, users can only interact with APIs and data to which they have access.

For example, cloud-hosted Retool organizations can grant Retool either Read and write or Read only access to your Google Sheets data. This option determines the scopes passed with the OAuth request. Retool recommends Read and write so that Retool can read and write spreadsheet data (e.g., create new sheets or update cell rows).

To create other Google API resources, or to use Retool's Google integrations with self-hosted deployments, you create Google Cloud projects and OAuth 2.0 credentials with scopes you define.

Shared user credentials

OAuth-based authentication with shared user credentials. The user creating the resource is prompted to authenticate with Google using an OAuth authentication flow, and subsequent API calls from Retool are made on behalf of the user that completed authentication. When building apps on top of Google Sheets, all users in a Retool organization can access and edit sheets that have been shared with the user who completed the authentication process.

OAuth 2.0 custom application

Authentication is performed using a custom OAuth 2.0 client app. You must create this client and then provide its credentials. Once configured, your users are redirected to to sign in and authorize Retool to access data.

OAuth apps typically require the following values during creation:

• OAuth callback URL: The URL to which users are redirected once they have successfully signed in.
• Scopes : The permissions granted to Retool. Each scope defines a specific set of permissions (e.g., messages:read to read messages users:write to create new users). You must ensure that any scopes defined in your OAuth app matches the scopes you specify when configuring the resource.

Once you've created an OAuth app you can obtain its credentials, such as the Client ID and Client secret. You then provide these to configure Retool for OAuth authentication.

Example credentials

Client ID: 1234567890-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Client Secret: ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
Auth URL: https://accounts.google.com/o/oauth2/auth
Token URL: https://oauth2.googleapis.com/token
Redirect URI: https://yourapp.com/oauth2/callback
Scopes: ["https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/userinfo.profile"]

You can also choose to include the client ID and client secret as a Base64-encoded string in the Authorization header.

Include Authorization header for OAuth requests is currently in public beta on Retool Cloud and for Self-hosted Retool.

Session-based

Session-based authentication has been deprecated. Use an alternative authentication method, if available.

Authentication is performed using session-based authentication. You must be able to obtain and provide these credentials to create the resource.

Credential	Description
Cookies to forward	The cookies to forward.
Enable an auth verification endpoint	Whether to use a verification endpoint to determine if the user needs to authenticate.
URL to link to for logging in	The URL with which users can authenticate.