{"slug":"linear","name":"Linear","domain":"linear.app","category":"Project management","summary":"Linear is self-serve. You create an OAuth app in your workspace settings, turn on the Public switch, and any Linear workspace can install it right away, with no app review. The only review is the optional listing in Linear's integration directory, which accepts only integrations built by formal companies.","tier":"self-serve","tierReason":"Once the Public switch is on, other workspaces can authorize the app straight away, and Linear's docs describe no review, verification or user cap before that.","quality":"researched","updatedAt":"2026-10-27","composio":{"status":"managed","note":"Composio has a managed Linear OAuth app, so you can prototype before you register your own. Register your own before launch so your app name shows on the consent screen. Composio's separate LINEAR_MCP toolkit needs your own OAuth app.","toolkit":"LINEAR"},"totals":{"effort":{"min":15,"max":45,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"firstConnection":"Today, in about 15–30 minutes"},"stages":[{"id":"build","name":"Your workspace","whoCanConnect":"Members of the workspace that owns the app (apps are private by default)","userSees":"Linear's authorization screen with your app name and the requested scopes","effort":{"min":15,"max":30,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":"Turn on the Public switch (distribution: public) on the OAuth app","evidence":{"kind":"docs","sources":["s1","s3"],"confidence":"high"}},{"id":"launch","name":"Public app","whoCanConnect":"Any Linear workspace. On Enterprise workspaces with app approvals turned on, an admin may have to approve the app first.","userSees":"The same authorization screen. Members of workspaces that require approval see a request screen until an admin approves the app.","effort":{"min":0,"max":15,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":null,"evidence":{"kind":"docs","sources":["s3","s4","s6"],"confidence":"high"}}],"requirements":[{"id":"linear-workspace","label":"A Linear workspace where you are an admin","detail":"Linear recommends a dedicated workspace just for managing the OAuth app, because every admin of that workspace can access the app and its credentials.","stage":"build","actor":"you","evidence":{"kind":"docs","sources":["s1","s2"],"confidence":"high"}},{"id":"redirect-uri","label":"Your redirect URI","detail":"Your OAuth client's callback URL. It must be an absolute HTTP or HTTPS URL, and an app can register up to 32 of them.","stage":"build","actor":"agent","evidence":{"kind":"docs","sources":["s1","s3"],"confidence":"high"}},{"id":"homepage-url","label":"A homepage or docs URL and a developer name","detail":"The app record requires a homepage or documentation URL, a developer name, and an app name that does not contain the word \"Linear\".","stage":"build","actor":"you","evidence":{"kind":"docs","sources":["s3"],"confidence":"high"}},{"id":"directory-assets","label":"Directory assets (optional)","detail":"You only need these to be listed in Linear's integration directory: a 320×320 color icon, a 320×320 white monochrome icon, and 1–3 showcase images at 1600×1000. Linear only lists integrations built by formal companies.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s2"],"confidence":"high"}}],"steps":[{"id":"open-oauth-apps","title":"Open OAuth applications in workspace settings","actor":"you","stage":"build","time":{"min":2,"max":5,"unit":"minutes"},"detail":"Sign in to Linear as a workspace admin. Go to Settings > API > OAuth applications and click + to create an app.","actions":["Sign in at linear.app","Go to Settings > API > OAuth applications","Click + (or open linear.app/settings/api/applications/new)"],"agentNote":"Once you are signed in, an agent can open the page and fill in the form.","gotcha":"If you create the app in your personal workspace, only that workspace's admins can manage it. Use a dedicated workspace instead.","link":{"label":"New OAuth application","url":"https://linear.app/settings/api/applications/new"},"evidence":{"kind":"docs","sources":["s1","s4"],"confidence":"high"}},{"id":"fill-app-form","title":"Fill in the app details and callback URLs","actor":"agent","stage":"build","time":{"min":5,"max":10,"unit":"minutes"},"detail":"Enter the app name, developer name, homepage URL, an optional description and icon, and your redirect URI under Callback URLs. Leave Refresh Tokens turned on (the default for new apps).","actions":["Application name (must not contain \"Linear\")","Developer name","Developer/homepage URL","Callback URLs: your redirect URI","Confirm Refresh Tokens is enabled","Optionally turn on webhooks and pick resource types"],"agentNote":"An agent can fill in every field. Stop before the secrets are shown.","gotcha":"The redirect_uri in your authorize request must exactly match a registered callback URL. A mismatch causes an 'Invalid redirect URI' error.","link":{"label":"New OAuth application","url":"https://linear.app/settings/api/applications/new"},"evidence":{"kind":"docs","sources":["s1","s3","s4"],"confidence":"high"}},{"id":"make-public","title":"Turn on the Public switch","actor":"you","stage":"build","time":{"min":1,"max":2,"unit":"minutes"},"detail":"Apps are private by default and can only be installed in the workspace that created them. Turn on Public so other workspaces can install the app. Linear documents no review for this.","actions":["Turn on Public","Click Create"],"agentNote":"An agent can flip the switch, but you should confirm you want other workspaces to be able to install the app.","gotcha":"If you leave it private, users from other workspaces can't authorize the app.","evidence":{"kind":"docs","sources":["s3","s4"],"confidence":"high"}},{"id":"copy-credentials","title":"Store the client ID and secret","actor":"you","stage":"build","time":{"min":2,"max":5,"unit":"minutes"},"detail":"Copy the client ID and client secret (plus the webhook signing secret, if you use webhooks) into your OAuth client's secret storage. You can rotate each secret separately later.","actions":["Copy Client ID","Copy Client Secret into your secret store","Copy the webhook signing secret if you need it"],"agentNote":"An agent can copy the client ID. You handle the client secret.","gotcha":"Rotating the client secret invalidates client_credentials tokens but does not revoke existing user tokens.","evidence":{"kind":"docs","sources":["s1"],"confidence":"high"}},{"id":"configure-client","title":"Configure your OAuth client and scopes","actor":"agent","stage":"build","time":{"min":5,"max":15,"unit":"minutes"},"detail":"Use authorize URL https://linear.app/oauth/authorize and token URL https://api.linear.app/oauth/token. Request scopes separated by commas (read, write, issues:create, comments:create, admin), and optionally actor=app. Access tokens last 24 hours, and each refresh returns a new refresh token.","actions":["Set the authorize and token URLs","Set scopes, e.g. read,write","Store the rotated refresh token after every refresh","Test by connecting your own workspace"],"agentNote":"An agent can set everything except the secret, which you enter yourself.","gotcha":"Refresh tokens rotate, so reusing an old one returns invalid_grant. Save the new refresh token from every refresh response.","link":{"label":"Linear OAuth 2.0 docs","url":"https://linear.app/developers/oauth-2-0-authentication"},"evidence":{"kind":"docs","sources":["s1","s7"],"confidence":"high"}},{"id":"submit-directory","title":"Optionally apply for the integration directory","actor":"you","stage":"launch","time":{"min":30,"max":120,"unit":"minutes"},"detail":"You don't need a listing for users to connect. To be listed, submit Linear's form and send your assets to integrations@linear.app. Linear says it generally rejects scripts, hobby projects and low-effort apps.","actions":["Complete the submission form","Email assets to integrations@linear.app"],"agentNote":"An agent can draft the copy. You submit the form and the assets.","link":{"label":"Integration directory","url":"https://linear.app/developers/integration-directory"},"evidence":{"kind":"docs","sources":["s2"],"confidence":"high"}}],"scopes":{"intro":"Linear doesn't classify scopes or require approval for any of them. Request the narrowest set that works. The admin scope is the broadest one.","tiers":[{"scope":"read","grants":"Read access (always included)","level":"basic","consequence":"Nothing"},{"scope":"write / issues:create / comments:create","grants":"Write access, or narrower create-only access","level":"basic","consequence":"Nothing"},{"scope":"admin","grants":"Admin-level endpoints","level":"sensitive","consequence":"No review. Linear advises requesting it only when absolutely needed. Installing users likely need to be admins (not confirmed)."}]},"blockers":[{"symptom":"Users from other workspaces can't install the app","cause":"The app is still private, which is the default distribution.","fix":"Turn on Public in the app settings.","evidence":{"kind":"docs","sources":["s3","s4"],"confidence":"high"}},{"symptom":"'Invalid redirect URI' at authorization","cause":"The redirect_uri sent doesn't match any registered callback URL.","fix":"Add the exact URL under Callback URLs.","evidence":{"kind":"community","sources":["s8"],"confidence":"medium"}},{"symptom":"invalid_grant on refresh","cause":"A stale refresh token was reused after rotation.","fix":"Save the new refresh token after each refresh. Linear allows replaying the original request within 30 minutes if a response is lost.","evidence":{"kind":"docs","sources":["s1","s7"],"confidence":"high"}},{"symptom":"A member sees an approval request screen instead of consent","cause":"Their Enterprise workspace has third-party app approvals turned on.","fix":"A workspace admin approves the app under workspace applications.","evidence":{"kind":"docs","sources":["s6"],"confidence":"medium"}}],"unknowns":[{"question":"Does making an app Public ever trigger a review by Linear?","why":"The docs describe the switch but say nothing about review.","resolve":"Create a test app, turn on Public, and install it from a second workspace."},{"question":"Do actor=app installs or the admin scope require a workspace admin to authorize?","why":"Not confirmed in the pages fetched.","resolve":"Check the Linear app/agent authentication docs, or test with a non-admin account."},{"question":"How long does a directory listing review take?","why":"Linear gives no timeline.","resolve":"Ask integrations@linear.app."}],"handoff":{"agentCan":["Open the OAuth app form and fill in the name, URLs and callback URLs","Configure your OAuth client's endpoints, scopes and client ID","Test a connection with your own workspace"],"youMust":["Sign in as a workspace admin (ideally in a dedicated workspace)","Turn on Public and click Create","Copy and store the client secret","Optionally submit the directory listing"]},"sources":[{"id":"s1","title":"OAuth 2.0 authentication","url":"https://linear.app/developers/oauth-2-0-authentication","publisher":"Linear developer docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s2","title":"Integration directory","url":"https://linear.app/developers/integration-directory","publisher":"Linear developer docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s3","title":"OAuth app manifests","url":"https://linear.app/developers/oauth-app-manifests","publisher":"Linear developer docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s4","title":"How to register your own Linear API OAuth app","url":"https://nango.dev/docs/api-integrations/linear/how-to-register-your-own-linear-api-oauth-app","publisher":"Nango docs","kind":"community","checkedAt":"2026-10-27"},{"id":"s5","title":"Rate limiting","url":"https://linear.app/developers/rate-limiting","publisher":"Linear developer docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s6","title":"Third-Party Application Approvals","url":"https://linear.app/docs/third-party-application-approvals","publisher":"Linear docs","kind":"search","checkedAt":null},{"id":"s7","title":"Linear OAuth refresh token invalid_grant","url":"https://nango.dev/blog/linear-oauth-refresh-token-invalid-grant","publisher":"Nango blog","kind":"search","checkedAt":null},{"id":"s8","title":"Linear MCP auth fails with Invalid redirect URI","url":"https://forum.cursor.com/t/linear-mcp-auth-fails-with-invalid-redirect-uri-cursor-anysphere-cursor-mcp-oauth-callback/158845","publisher":"Cursor forum","kind":"search","checkedAt":null},{"id":"s9","title":"Managed auth toolkits","url":"https://docs.composio.dev/toolkits/managed-auth.md","publisher":"Composio docs","kind":"composio","checkedAt":"2026-10-27"}],"feedback":{}}