Skip to main content

Connect to GraphQL

Connect GraphQL APIs to Retool and query and mutate data.

Create a GraphQL resource to connect Retool to GraphQL APIs. GraphQL resources are generic integrations that enable you to securely connect to external services using a type-safe query language and build internal tools, admin panels, and workflows with strongly-typed queries and mutations.

What you can do with GraphQL in Retool​

  • Request specific data with typed GraphQL queries, benefiting from schema validation and type checking.
  • Create, update, and delete data using GraphQL mutations with automatic error handling.
  • Pass dynamic parameters to queries and mutations with typed GraphQL variables.
  • Explore GraphQL schemas automatically to discover available types, queries, and mutations.
  • Authenticate with Bearer tokens, Basic auth, OAuth 2.0, AWS Signature V4, and more.

Before you begin​

To connect a GraphQL API to Retool, you need the following:

  • API credentials: API keys, OAuth credentials, or other authentication method required by the GraphQL API.
  • GraphQL endpoint URL: The URL of the GraphQL API endpoint.
  • Retool permissions: Edit all permissions for resources in your organization.

Create a GraphQL resource​

Follow these steps to create a GraphQL resource in Retool.

Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for GraphQL and click the GraphQL tile to begin configuration.

Searching for GraphQL in the resource creation page.

Configure connection settings​

Configure the following connection settings for your GraphQL resource.

GraphQL connection settings form.

Resource name and description​

Specify a name for the resource that indicates which GraphQL API it connects to. Include a description that can provide more context to users and Assist about how to use the resource.

Example NameExample Description
Countries GraphQL APIA GraphQL API resource for accessing country information.
SpaceX GraphQL APIA GraphQL API resource for SpaceX launch and rocket data.

Base URL​

The GraphQL endpoint URL. All queries and mutations are sent to this endpoint.

Examples
https://countries.trevorblades.com
https://spacex-production.up.railway.app
https://api.example.com/graphql

Headers​

Global headers applied to all requests. Add headers as key-value pairs.

Enable introspection​

Enable schema introspection to automatically discover available types, queries, and mutations. This provides autocomplete and type checking when writing queries.

Configure authentication​

GraphQL supports multiple authentication methods based on your API requirements.

Authentication methodUse cases
Auth0 Client CredentialsAuth0 for identity and access management. Retool handles OAuth flow and token management automatically.
AWS Signature V4AWS-hosted APIs requiring signed requests (API Gateway). Retool signs each request using AWS Signature Version 4.
Basic authenticationUsername and password credentials sent with each request. Retool encodes credentials as base64 in the Authorization header. Common for simple APIs.
Bearer tokenStatic API token authentication. Retool sends the token as Authorization: Bearer {token}.
CustomCustom authentication logic not covered by standard methods, such as multi-step flows. Add custom headers and authentication workflow using JavaScript. Test connection disabled for custom auth.
NonePublic endpoints or custom authentication via headers. Add authentication tokens as custom headers.
OAuth 2.0User authentication via OAuth 2.0. Use Authorization Code flow for user credentials or Client Credentials for server-to-server authentication with automatic token refresh.

Select an authentication method from the Authentication dropdown and provide the required credentials. Retool encrypts these credential fields automatically.

GraphQL authentication settings dropdown.

Test the connection​

Click Test connection to verify Retool can connect to your GraphQL API. A successful test confirms the endpoint URL is accessible and authentication credentials are valid.

If the connection test fails, verify:

  • GraphQL endpoint URL is correct and accessible from Retool
  • Authentication credentials are valid and not expired
  • API accepts requests from Retool's IP addresses (for Cloud organizations)
  • Headers are formatted correctly

Save the resource​

Click Create resource to save your GraphQL resource. The resource is now available to use in apps, workflows, and agent tools across your Retool organization.

Interact with GraphQL data​

Once you've created a GraphQL resource, you can interact with GraphQL data using Retool.

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

  • To use GraphQL data in the app builder, reference the resource in the prompt with @, such as @Countries GraphQL API. Refer to the data and functions documentation to learn more.
  • For classic apps, workflows, and agents, refer to the GraphQL queries documentation to learn how to write a resource query.

Best practices​

Follow these best practices to maintain the security of your GraphQL resource.

  • Store credentials securely: Retool encrypts your GraphQL API credentials automatically, so you don't need to route them through a separate secrets store.
  • Use HTTPS only: Always connect to GraphQL APIs over HTTPS to encrypt data in transit and protect authentication credentials.
  • Use resource environments: Organizations on an Enterprise plan can configure multiple resource environments to maintain separate configurations for production, staging, and development.
  • Apply least privilege: Use API keys with minimal required permissions. Create separate keys for different environments.
  • Rotate credentials regularly: Follow your API provider's recommendations for credential rotation and key management.