Authentication overview
Retool is designed to facilitate the rapid development of internal tools by connecting to various data sources, including databases, APIs, and SaaS applications. Central to this functionality is its authentication system, which manages secure access to these external services. Retool does not store sensitive user data from integrated services directly but rather stores the credentials required to authenticate with those services (e.g., API keys, OAuth tokens) in an encrypted format within its environment. This approach allows Retool applications to make authenticated requests on behalf of the application or the end-user, depending on the configuration.
The platform supports a range of authentication types to accommodate different data sources and security requirements. For databases, this typically involves standard username/password combinations or IAM roles. For APIs, methods like API keys, OAuth 2.0, and custom HTTP headers are commonly used. Retool also provides mechanisms for securely handling environment variables and secrets, ensuring that sensitive information is not exposed in the application code itself. Understanding these methods is crucial for building secure and functional internal tools within the Retool ecosystem.
Supported authentication methods
Retool offers several authentication methods to connect to various data sources and APIs. The choice of method depends on the specific service being integrated and its supported authentication protocols. Each method provides a different level of security and operational complexity.
The following table outlines the primary authentication methods supported by Retool:
| Method | When to Use | Security Level |
|---|---|---|
| API Key | Connecting to APIs that use a single, secret key for authentication (e.g., Stripe API, Twilio API). Often passed in headers or query parameters. | Moderate (key security depends on storage and rotation practices) |
| OAuth 2.0 | Connecting to services where user consent is required, or where access tokens need to be refreshed without re-authentication (e.g., Google APIs, Salesforce). | High (token-based, scope-limited, refreshable) |
| Basic Authentication | Connecting to APIs or databases that accept a username and password encoded in the HTTP Authorization header. |
Moderate (credentials are base64 encoded, requires HTTPS for transport security) |
| Bearer Token | Connecting to APIs that use a token (often JWT) in the Authorization: Bearer header. Common with many modern REST APIs. |
High (token-based, often short-lived) |
| Custom Headers | For APIs requiring unique header-based authentication schemes not covered by standard methods, or for passing custom tokens. | Varies (depends on the custom scheme's implementation) |
| Database Credentials | Direct connections to SQL and NoSQL databases using username and password. | Moderate (depends on database configuration, network security) |
| AWS IAM Roles | Connecting to AWS services by assuming an IAM role, avoiding hardcoded credentials. | High (role-based access control, temporary credentials) |
Getting your credentials
The process for obtaining credentials varies significantly depending on the specific service you intend to connect to. Generally, credentials are provisioned through the administrative interface or developer console of the external service.
- API Keys: For services like Stripe's API or Twilio's API, API keys are typically generated in the developer dashboard. These keys often come in pairs (e.g., publishable and secret keys), where the secret key must be protected.
- OAuth 2.0: To use OAuth 2.0, you usually need to register your Retool instance as an application with the external service (e.g., Google Cloud Console for Google APIs, PayPal Developer Dashboard for PayPal). This process typically yields a Client ID and Client Secret. Retool then handles the redirection and token exchange flow.
- Database Credentials: For databases, you will need to create a user with appropriate permissions within your database management system (e.g., PostgreSQL, MySQL, MongoDB). This involves defining a username and password, and ensuring the database is accessible from Retool's environment (or your self-hosted Retool instance).
- AWS IAM Roles: For AWS services, you would configure an IAM role with the necessary permissions and then configure Retool to assume that role. This is a recommended practice over hardcoding AWS access keys. AWS documentation on IAM roles provides detailed guidance.
Once you have obtained your credentials, you will configure them within Retool's Resource settings. Retool allows you to define resources (e.g., a specific database connection, an API endpoint) and associate the necessary authentication details with them. These credentials are encrypted at rest and in transit within Retool's infrastructure, or within your own infrastructure if using a self-hosted deployment.
Authenticated request example
When connecting to an API using an API key, Retool allows you to configure the key directly within the resource settings. For example, if connecting to an API that requires an API key in the Authorization header as a Bearer token, the configuration in Retool would handle this automatically once the resource is set up. The actual request from your Retool application would then include the necessary header without exposing the key in your frontend code.
Consider a REST API resource configured in Retool to use an API key. When you make a query from a Retool application, such as fetching data from https://api.example.com/data, Retool internally constructs the HTTP request, injecting the configured authentication details. For an API key named X-API-KEY with value your_secret_api_key, the outgoing request might look conceptually like this (Retool abstracts this from the developer):
GET /data HTTP/1.1
Host: api.example.com
X-API-KEY: your_secret_api_key
Content-Type: application/json
For OAuth 2.0, after the initial setup with Client ID and Client Secret, Retool manages the token exchange and refresh process. When a Retool application makes a request to an OAuth-protected resource, Retool ensures that a valid access token is included in the request, typically in the Authorization: Bearer header. The developer writing the Retool application simply selects the configured OAuth resource, and Retool handles the underlying authentication flow.
Security best practices
Implementing strong security practices is critical when integrating external services with Retool to protect sensitive data and prevent unauthorized access. The following recommendations align with general API security principles and Retool's capabilities:
- Least Privilege: Configure credentials (e.g., database users, API keys) with the minimum necessary permissions. For example, a Retool application that only reads data should not have write or delete permissions on the connected database or API.
- Credential Rotation: Regularly rotate API keys, database passwords, and OAuth client secrets. This reduces the window of exposure if a credential is compromised. Retool's resource configuration allows for updating credentials without redeploying applications.
- Environment Variables and Secrets: Utilize Retool's built-in support for environment variables and secrets management. Avoid hardcoding sensitive information directly into queries or JavaScript code. This practice ensures that secrets are managed securely and can differ between development, staging, and production environments.
- Secure Network Configuration: If using a self-hosted Retool instance, ensure it is deployed within a secure network environment. For cloud-hosted Retool, restrict database and API access to Retool's IP addresses where possible (IP whitelisting).
- OAuth Scopes: When using OAuth 2.0, request only the necessary scopes. Overly broad scopes can grant more access than required, increasing the risk in case of a token compromise.
- Audit Logs: Regularly review audit logs provided by Retool and your integrated services. These logs can help detect unusual activity or unauthorized access attempts.
- HTTPS Everywhere: Ensure all connections to external services use HTTPS to encrypt data in transit. Retool enforces HTTPS for its own platform and encourages its use for all integrated resources. This aligns with modern web security standards for protecting data from eavesdropping and tampering, as detailed in Mozilla's HTTPS explanation.
- Access Control: Implement granular user and group permissions within Retool to control who can access, create, or modify resources and applications. This prevents unauthorized users from interacting with sensitive data or making changes to critical internal tools.
- Regular Updates: Keep your Retool instance (especially self-hosted versions) and any associated libraries or connectors updated to benefit from the latest security patches and features.