Skip to main content

Linear Setup

Configuring a custom Linear OAuth app for use with Caddi

Linear lets you register an OAuth application in workspace settings with no vendor approval needed. One detail is worth planning for up front: every admin of the workspace hosting the app can see its client secret.

Linear recommends creating the OAuth application in a workspace dedicated to that purpose, because every admin of the hosting workspace has access to the app — including its client secret. If your main workspace has many admins, consider a separate one.

Before you start

You'll need:

  • Admin access to a Linear workspace that will host the application

  • Owner or Admin access to your Caddi organization

Step 1: Create the OAuth application in Linear

  1. Go to linear.app/settings/api/applications/new. You can also navigate there via workspace name → Settings → API → Applications → Create new application.

  2. Application name — Caddi. Fill in the developer name, description, and icon if you want them on the consent screen.

  3. Callback URLs — enter https://app.trycaddi.com/oauth-callback. Linear supports multiple callback URLs if you need more later.

  4. Save, then copy the Client ID and Client Secret.

  5. If people outside this workspace need to connect, enable public or multi-workspace installation on the app.

Callback URLs must match exactly at authorization time — the value Caddi sends has to be byte-identical to one you registered.

Step 2: Configure Linear in Caddi

This step must be completed by a Caddi organization owner or admin.

  1. In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.

  2. Find Linear in the list and click Configure.

Enter the following values:

  • Client ID — from your Linear OAuth application

  • Client Secret — from the same application

  • OAuth Scopes — comma-separated. Leave blank to use Caddi's defaults, or enter read,write for full read and write access. Do not request admin — Linear's own documentation says never to ask for it unless absolutely necessary, and Caddi doesn't need it.

Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.

Step 3: Connect your account

  1. Go back to the My Connections tab and find Linear.

  2. Click Connect + and sign in to Linear.

  3. Select the workspace you want Caddi to work in. Linear tokens are scoped to one workspace, so a user working across three workspaces will need three connections.

  4. Approve the request. You'll be returned to Caddi with the connection active.

How the connection behaves

  • Each user connects their own Linear account, per workspace. A token is tied to both the user and the workspace they selected.

  • read is always granted, whatever you request, so write alone still includes read. Requesting read,write explicitly is clearer.

  • Access tokens last 24 hours and refresh automatically. Linear allows a 30-minute grace window to retry a failed refresh, so a transient failure isn't fatal.

  • Issues created by Caddi are attributed to the authorizing user by default, which is usually what you want in an audit trail.

  • A custom connection replaces the standard one. Members of your organization will only see the option to connect through your app.

  • Revoking access. Delete the application in Linear workspace settings.

Troubleshooting

A user connects but sees no issues

They authorized a different workspace than the one the loop targets. Linear tokens are per-workspace — reconnect and select the right one.

A callback error at sign-in

The callback URL registered on the application doesn't exactly match https://app.trycaddi.com/oauth-callback. Linear matching is byte-for-byte.

Caddi can read but not create issues

Only the default read scope was granted. Set OAuth Scopes to read,write and have the user reconnect.

Someone unexpected can see the app's client secret

Expected behaviour — every admin of the hosting workspace can. Move the application to a dedicated workspace with a small admin group.

Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.

Automation ideas

Law Firms

Support request → tracked issue

Caddi turns inbound requests into Linear issues with the right team, label, and priority, and reports back when they close.

Recurring problem → grouped issue

Caddi spots repeat reports of the same underlying problem and consolidates them into one Linear issue with the individual reports linked.

Related Articles
Did this answer your question?