Connect to Linear
You can connect to Linear using Retool's GraphQL integration and make it available as a resource. Once complete, you can write queries to interact with the Linear API.
Requirements
All users for Retool organizations on Free or Team plans have global Edit permissions and can add, edit, and remove resources. If your organization manages user permissions for resources, you must be a member of a group with Edit all permissions.
To create your Linear resource, you need:
- Linear GraphQL API connection details.
- A personal API key or OAuth 2.0 credentials.
Linear supports API key authentication and OAuth 2.0. You must provide an API key or authenticate with OAuth 2.0 for Retool to authorize requests.
If Linear is behind a firewall, you must also allow access from Retool's IP addresses. Add these IP addresses to your firewall's allowlist before you create the resource.
1. Create a new GraphQL resource
Retool can connect to almost any API or database, and has built-in integrations for popular data sources. Sign in to your Retool organization and create a new GraphQL resource from the Resources tab.
2. Configure the resource
Provide the necessary details to configure the resource so Retool can connect to Linear. Not all settings are required but refer to the Linear documentation to learn what is needed.
General
These settings configure the name and location of the resource within Retool.
Name
The name to use for the resource (e.g., Linear).
Folder
The folder in which to save the resource.
Description
A brief description of the resource (e.g., Project tasks).
Credentials
These settings configure how Retool connects to Linear.
Base URL
The base URL for the Linear API. This must be an absolute URL. Use https://api.linear.app/graphql.
URL parameters
Key-value pairs to include as URL parameters with Linear API requests. No additional URL parameters are required.
Headers
Key-value pairs to include as headers with Linear API requests. If you're using a personal API key for authentication, include the following key-value pair:
| Key | Value |
|---|---|
Authorization | personal_api_key |
If you're using OAuth 2.0 for authentication, include the following key-value pair:
| Key | Value |
|---|---|
Authorization | Bearer OAUTH2_TOKEN |
Body
Key-value pairs to include in the body of Linear API requests. No additional body values are required.
Cookies
Cookies to include with Linear API requests. No cookies are required.
Forward all cookies
Whether to forward all cookies. This is useful if you have dynamic cookie names.
Authentication
The method of authentication to use with Linear. Select None if you're using a personal API key for authentication. Otherwise, select OAuth 2.0 and provide the following information.
Retool currently supports the server-side OAuth 2.0 authentication flow as well as the Client Credentials flow. In both cases, you must use the OAUTH2_TOKEN placeholder in order to inform Retool where to place the OAuth access token in the API request. A common location for this is as a header such as Authorization: Bearer OAUTH2_TOKEN.
| Setting | Description |
|---|---|
| Use Client Credentials Flow | Whether to obtain an access token as an app, rather than a user. Authentication will be shared across users. |
| Authorization URL | The OAuth 2.0 callback URL. Use https://linear.app/oauth/authorize. |
| Access Token URL | The OAuth 2.0 authorization URL. Use https://api.linear.app/oauth/token. |
| Client ID | The OAuth 2.0 client ID. |
| Client Secret | The OAuth 2.0 client secret. |
| Scopes | The scope of the access to request. Multiple scopes need to be separated by a space. Learn more about the available scopes in the Linear documentation. |
| Audience | The OAuth 2.0 audience. |
| Enable an auth verification endpoint | Whether Retool uses a verification endpoint to determine if a user should be prompted to authenticate when an app is first loaded. |
| Share credentials between users | Whether to share authentication credentials between users. All requests to the API will be executed as the authenticated user. |
Disable Introspection
The Linear API supports introspection, so leave this enabled. Disabling introspection reduces the usability of GraphQL, as auto-complete and linting for this resource will no longer work.
3. Save the resource
Click Test Connection to verify that Retool can connect to Linear. If the test fails, check the resource settings and try again. Testing a connection only checks whether Retool can successfully connect to the resource. It cannot check whether the provided credentials have sufficient privileges or can perform every supported action.
Click Create resource to complete the setup. You can then click either Create an app to immediately start building a Retool app or Back to resources to return to the list of resources.
Wrap up
Your Linear resource is now ready to use. You write queries using GraphQL schema.
To verify you can successfully interact with Linear, write a test query to retrieve some data. The following example retrieves information about the authenticated user. You can also see the GraphQL APIs page for more examples.
query Me {
viewer {
id
name
email
}
}