Skip to main content

Connect to GraphQL

Learn how to connect to GraphQL APIs and query, mutate data in Retool.

Create a GraphQL resource to connect Retool to GraphQL APIs. GraphQL resources 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​

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

For quick, one-off GraphQL calls that don't require authentication, you can use the built-in GraphQL query type available from the Resource dropdown in the query editor. This allows you to specify the GraphQL endpoint URL and query directly in the query without creating a resource. However, if your API requires authentication, create a GraphQL resource instead—resources securely encrypt credentials and authentication details.

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.

1. 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.

2. 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.

3. 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. For sensitive values like API keys, tokens, and secrets, use configuration variables or rather than hardcoding them.

GraphQL authentication settings dropdown.

4. 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

5. 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.

Query GraphQL data​

Once you've created a GraphQL resource, you can query it in apps, workflows, and agent tools.

Create a query​

You can create a GraphQL query in a Retool app using Assist to generate queries with natural language, or manually using code.

Use Assist to generate queries from natural language prompts. Assist can create GraphQL queries and mutations to retrieve and manipulate data from your GraphQL resource.

To create a query with Assist:

  1. In the Retool app IDE, click the Assist button at the bottom of the left toolbar to open the Assist panel (if not already visible).
  2. Write a prompt describing the data you want to retrieve, referencing your resource using @.
  3. Press Enter to submit the prompt.
  4. Select your GraphQL resource when prompted.
  5. Review the generated query and click Run query to add it to your app.
Example prompt
query the first 10 repositories using @GraphQL

Query configuration fields​

Each GraphQL query has the following configuration fields:

GraphQL operation​

The GraphQL query or mutation to execute using standard GraphQL syntax. Write your operation with typed variables for any dynamic values.

URL parameters​

Query parameters appended to the GraphQL endpoint URL. Add parameters as key-value pairs to build the query string.

Variables​

Variables passed to your GraphQL operation. GraphQL queries cannot contain embedded expressions directly. To pass dynamic values from your Retool app, declare them as variables in your GraphQL operation and provide their values in the Variables field below.

Variables example
query GetUsers($status: String!, $limit: Int!) {
  users(status: $status, limit: $limit) {
    id
    name
    email
  }
}

Common use cases​

The following examples demonstrate typical GraphQL operations in Retool apps.

fetch data with a query

First, create a GraphQL query to fetch data.

Write the query:

Example query
query GetActiveUsers($limit: Int!) {
  users(status: "active", limit: $limit) {
    id
    name
    email
    createdAt
  }
}

Next, add a Table component to the app, set its Data property to {{ getUsersQuery.data.users }}, and enable pagination. You can then specify the number of table rows per page and reference this in the query's limit variable using {{ usersTable.pagination.pageSize }}.

create data with a mutation

First, add a Form component (form1) with input fields for the data you want to collect.

Next, create a GraphQL mutation:

Example mutation
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      name
      email
    }
    errors {
      field
      message
    }
  }
}

Add variables with form data:

Example variables
{
  "input": {
    "name": {{ form1.data.name }},
    "email": {{ form1.data.email }},
    "role": {{ form1.data.role }}
  }
}

Then, add an event handler to the form's Submit event that runs the mutation and displays a success notification.

update data with a mutation

First, add a Form component with fields pre-populated from selected row data.

Next, create an update mutation:

Example mutation
mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
  updateUser(id: $id, input: $input) {
    user {
      id
      name
      email
      updatedAt
    }
    errors {
      field
      message
    }
  }
}

Add variables:

Example variables
{
  "id": {{ table1.selectedRow.data.id }},
  "input": {
    "name": {{ form1.data.name }},
    "email": {{ form1.data.email }}
  }
}

Then, add an event handler that runs the mutation when the form is submitted and refreshes the data query.

delete data with confirmation

First, add a Button component in your table's action column.

Next, create a delete mutation:

Example mutation
mutation DeleteUser($id: ID!) {
  deleteUser(id: $id) {
    success
    errors {
      message
    }
  }
}

Add variables:

Example variables
{
  "id": {{ table1.selectedRow.data.id }}
}

Then, add an event handler to the button's Click event:

  1. Action: Show confirmation modal
  2. If confirmed, trigger the delete mutation
  3. Then refresh the data query
handle paginated data

For GraphQL APIs with cursor-based pagination, use the pageInfo pattern with variables.

Write the query with pagination fields:

Example query with pagination
query GetUsers($cursor: String, $limit: Int!) {
  users(after: $cursor, first: $limit) {
    edges {
      node {
        id
        name
        email
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Set variables to control pagination:

Example variables
{
  "cursor": {{ table1.pagination.cursor }},
  "limit": 20
}

Use the pageInfo.endCursor value from the response to fetch the next page by updating the cursor variable.

Best practices​

Follow these best practices to optimize performance, maintain security, and ensure data integrity when working with GraphQL APIs.

Performance​

  • Request specific fields: Only request the fields you need to reduce payload size and improve response times.
  • Use fragments: Define reusable fragments for common field sets to keep queries maintainable.
  • Batch operations: When available, use GraphQL batch queries to fetch multiple records in a single request.
  • Enable caching: For data that doesn't change frequently, enable query caching to reduce API calls.
  • Set appropriate timeouts: Configure query timeouts based on expected API response times.

Security​

  • Use configuration variables: Store API keys and tokens in configuration variables or rather than hardcoding them.
  • Use HTTPS only: Always connect to GraphQL APIs over HTTPS to encrypt data in transit and protect authentication credentials.
  • Validate user input: Sanitize and validate all user input before including it in variables to prevent injection attacks.
  • 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.

Data integrity​

  • Handle GraphQL errors: Check the errors field in GraphQL responses and display appropriate error messages to users.
  • Use typed variables: Define variable types in your GraphQL operations to benefit from type checking and validation.
  • Verify mutations succeeded: Check mutation responses for success indicators before updating UI or showing success messages.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic.
  • Log API interactions: Enable query logging to track GraphQL operations and responses for debugging and auditing.