OAuth app readiness guide · Project management

Getting your Linear app ready for real users

Tested in a real setup attemptChecked 2026-10-28linear.app

Verdict. The easiest app in the library: a public OAuth app in about 4 minutes, no review, no install cap. The one trap is that new apps are private by default, so your first customer cannot connect unless you switch on "Public".

At a glance

The answer in one screen

Ease of creation

Easy

About 4 minutes in our test, plus workspace onboarding if the workspace is new.

Ease of approval

None

No review. Public availability was immediate.

Your hands-on time

5 to 15 min

Form, redirect URL, one toggle. A new workspace adds a short onboarding.

Waiting on the provider

None

Nothing to wait for.

Do you need your own app yet?

Check Composio first; your own app is cheap here.

We could not confirm a Composio-managed Linear app. Since your own app takes minutes and needs no review, bringing your own is low cost.

Watch out: decisions you can't undo

New apps are private by default. Turn on Public before you share an install link with anyone. A Developer URL is required for public apps and is shown to users.
The workspace that owns the app sees its secret. Create the app in a dedicated workspace with few admins.
Refresh tokens rotate. Store the newest refresh token every time. All apps were moved to this system on April 1, 2026.

Agent an agent can do it You needs you Waiting on the provider

Prerequisites

What to have ready

To create and connect

A Linear workspace to own the app (ideally dedicated, few admins)
A Developer URL (homepage or docs page). Required for public apps
The Composio callback URL from your auth config

For approval (can take days)

Nothing. There is no review.

App types

Which one is right for an agent product?

Private OAuth app

The default after creation.

Who can install: Your own workspace only
Review: None
Use it for: Internal tools and testing

Recommended for agents

Public OAuth app

After turning on the Public toggle.

Who can install: Any Linear workspace
Review: None
Use it for: Agent products with customers

Client credentials

Optional toggle on the app.

Who can install: Server-to-server in one workspace
Review: None
Use it for: Background jobs acting as the app, 30-day tokens

Act as the app, not the userAdd actor=app to the authorize URL so issues and comments are attributed to your agent instead of the person who connected. Linear's consent screen then shows the app as the actor. Official docs

Creation steps

Who does what, and how long it takes

YouSign in and finish onboarding
1 to 2 min
In a brand-new workspace, onboarding ("Set up your profile") blocks Settings until it is done. Linear links may open the desktop app; choose "Open here instead".
AgentOpen Settings, API, New application
30 sec
Path: /settings/api/applications/new in your workspace.
AgentFill the form
2 min
Application name, developer name, Developer URL, description, redirect URI. All are shown to users at consent.
AgentTurn on Public
5 sec
Off by default. Leave client credentials and webhooks off unless you need them.
YouApprove Create
5 sec
The app is created instantly with "Availability: Publicly available". Client ID is shown; the secret is masked.
YouCopy credentials into Composio
2 min
Create a custom auth config for the linear toolkit with the scopes from section 4.
YouTest from a second workspace
5 min
Check the consent screen, including the team-access choice users will see.

Total in our test: about 4 minutes of agent work, onboarding and one approval.

Scopes

What each permission costs you

Linear has no scopes on the app itself. You request them in the authorize URL, so changing scopes means changing your Composio auth config, not the app.

Agent use case	Scopes	What it costs you
Read issues, projects, teams	`read`	Always included
Create issues and attachments	`issues:create`	No review
Comment on issues	`comments:create`	No review
Broad edits	`write`	No review, but users see broad access
Admin endpoints	`admin`	Only when essential; scares admins at consent

Minimal set: "Triage bot" agentreadissues:createcomments:create

Narrower than write, and reads better on the consent screen.

Changing scopes later

Scopes live in the authorize URL, so update the Composio auth config and ask users to reconnect.
No re-review, because there is no review.
Requesting different scopes for client credentials revokes the existing app tokens.

Approval and distribution

Review, cost and renewal

When you need it: Never for OAuth. Linear's integrations directory listing is a separate, optional step. Cost: None. Renewal: None.

Review

None

Public apps work immediately.

What you submit

Nothing for OAuth

Common rejection reasons

Not applicable

Before approval: what works and what's capped

Build and test

Private app in your workspace.

Limit: Other workspaces cannot connect until Public is on.

First customers

Public app, any workspace.

Limit: Users may grant access to only some teams.

Scale

Same app.

Limit: Standard API rate limits only.

Users choose which teams you seeThe consent screen offers "All public teams" or "Only select teams". Private teams are not in "All public teams". An agent may see fewer issues than the user expects. Tested

Data use and compliance

Rules that shape agent design

Your terms apply. Linear's consent screen tells users that your app's use of their data is governed by your own terms and privacy policy, not Linear's.
Revocable by admins. Workspace owners and admins can revoke the connection at any time in Settings.

Design impactPublish a privacy policy before your first customer, and handle revoked tokens gracefully. Tested

Common blockers

Symptom, cause, fix

Symptom	Cause	Fix
Customer cannot install the app	App is still private	Turn on Public in the app settings
Agent cannot see some issues	User picked "Only select teams" or the issues are in private teams	Ask the user to reconnect and include those teams
Connections fail after a day	24-hour access token not refreshed	Refresh before expiry and store the newest refresh token
Comments show as the user, not the agent	Default actor is the user	Add `actor=app` to the authorize URL

Sources

Where every claim comes from

Claim	Source
Apps are private by default; Public toggle needed	Tested in our setup
No review; public availability immediate	Tested in our setup
Consent screen offers team selection	Tested in our setup
24-hour access tokens, rotating refresh, 30-minute replay	Official docs
Composio has a managed Linear app	Not verified

All sources

Linear: OAuth 2.0 authentication linear.app
Composio: Managed vs custom auth docs.composio.dev