Linear
linear.app · Project management · for: Create, read, update, and manage issues, projects, and cycles on behalf of the user.
Create your OAuth app at https://linear.app/settings/api/applications/new and set up your initial PKCE flow.
Your path at a glance
Watch out for
- BlockerWorkspace Admin Consent Requirementwhy & fix →
- WarningGraphQL Query Complexity Limitswhy & fix →
- WarningApp Default Distribution is Privatewhy & fix →
- InfoRefresh Token 30-Minute Grace Periodwhy & fix →
Before you start
Steps
Configure OAuth
Customer-side setup
- 7Customer Workspace Admin ApprovalCustomer admindetails →
Copy & paste
readwriteissues:create- Developer console
- https://linear.app/settings/api/applications/new
- OAuth docs
- https://linear.app/developers/oauth-2-0-authentication
- Authorize URL
- https://linear.app/oauth/authorize
- Token URL
- https://api.linear.app/oauth/token
Show prompt
Implement Linear OAuth 2.0 PKCE authentication flow for an AI agent integration using standard HTTP clients. Store access tokens (24h lifespan) and handle automatic refresh token rotation. Use 'read' and 'write' scopes, and support both actor=user and actor=app parameters in the authorization URL.
Show dotenv
LINEAR_CLIENT_ID="your_client_id_here" LINEAR_CLIENT_SECRET="your_client_secret_here" LINEAR_REDIRECT_URI="https://your-domain.com/api/auth/callback/linear" LINEAR_SCOPES="read write" LINEAR_ACTOR_MODE="user"
Show json
{
"name": "AI Agent Integration",
"description": "Manages Linear issues, projects, and cycles",
"distribution": "public",
"developerUrl": "https://your-domain.com",
"redirectUris": [
"https://your-domain.com/api/auth/callback/linear"
],
"scopes": [
"read",
"write"
]
}Why & details
The reasoning, evidence and sources behind everything above. Hover a badge to see its sources.
The full picture
Self-serve, review to scale
Linear OAuth setup is self-serve and fast, supporting instant public distribution without mandatory app review. Workspace admin approval is required for customers installing third-party integrations.
Anyone with a Linear account can register an OAuth application immediately. App distribution can be switched to public without prior review, but optional listing in the official Integration Directory requires manual submission and review.
Rating: Self-serve with extra configuration, policies or an optional review.
Register a private OAuth application in Linear workspace settings and execute PKCE flow.
Set distribution mode to public in app settings or manifest to allow any customer workspace admin to authorize.
What affects your setup
- Manual app review
Listing in the official Linear Integration Directory requires emailing required assets to integrations@linear.app for manual review.
- Customer admin consent
Installing third-party OAuth integrations generally requires workspace admin permissions in Linear.
- Redirect URI rules
Redirect URIs must be absolute HTTP or HTTPS URLs, with a minimum of 1 and maximum of 32 unique URIs allowed.
- Token lifecycle gotchas
Access tokens expire after 24 hours. Refresh tokens feature a 30-minute grace period allowing request replay in case of network issues.
- Marketplace listing optional
Directory listing is optional; public OAuth apps can connect to any workspace via standard OAuth flow without being listed.
Before you start — why each matters
- Linear Workspace Account — An active Linear account and workspace to access developer settings and create applications.
- Workspace Admin Permissions for Customers — Customer users connecting the integration must hold admin permissions in their Linear workspace.
How well this guide is backed
Step details
Decide whether the OAuth app will operate on behalf of the authorizing user (actor=user) or as its own bot identity (actor=app). Determine required scopes (read, write).
🤖 What an agent can do: Generate configuration templates and specify authorize URL parameters including actor mode.
https://linear.app/developers/oauth-actor-authorization ↗Navigate to Linear API settings and create a new application or submit an app manifest.
👤 Why you: Needs your logged-in console session (2FA/CAPTCHA)
🤖 What an agent can do: Generate app manifest JSON pre-populated with callback URLs and scope definitions.
https://linear.app/settings/api/applications/new ↗Input absolute HTTP/HTTPS redirect URIs (up to 32) and securely capture the Client ID and Client Secret.
👤 Why you: A product/business judgement only you can make
🤖 What an agent can do: Draft environment variable structure and store secrets safely in local environment files.
https://linear.app/settings/api/applications/new ↗Implement Authorization Code grant with PKCE (S256 code challenge). Support access token expiration (24h) and background refresh logic with 30-minute grace period handling.
🤖 What an agent can do: Write full PKCE authorization code exchange and auto-refresh logic with handling for refresh token replay limits.
https://linear.app/developers/oauth-2-0-authentication ↗If directory visibility is desired, prepare color/monochrome icons and showcase screenshots, then submit via email to integrations@linear.app.
👤 Why you: Waiting on the provider's reviewers
🤖 What an agent can do: Format asset metadata and draft directory submission request email.
https://linear.app/developers/integration-directory ↗Update app settings or manifest field `distribution` to `public` so external Linear workspace admins can connect.
👤 Why you: A product/business judgement only you can make
🤖 What an agent can do: Update app manifest file to set distribution=public.
https://linear.app/developers/oauth-app-manifests ↗Prompt customer Linear workspace admins to complete the OAuth consent flow to install the application in their workspace.
👤 Why you: Your customer's admin must act
🤖 What an agent can do: Construct the exact authorization URL parameterized with workspace hints and state tokens.
Gotchas explained
- BlockerWorkspace Admin Consent Requirement
Installing third-party integrations into a Linear workspace requires workspace admin privileges.
Fix: Ensure your onboarding flow explicitly instructs users that a Linear workspace admin must authorize the integration.
- WarningGraphQL Query Complexity Limits
OAuth apps are capped at 2,000,000 GraphQL complexity points per hour and 10,000 points per individual query in addition to the 5,000 requests/hour limit.
Fix: Track rate limit headers (X-RateLimit-Requests-Remaining) and avoid over-fetching deeply nested GraphQL relations.
- WarningApp Default Distribution is Private
Newly created OAuth apps default to private distribution and cannot be authorized by users in other Linear workspaces.
Fix: Set distribution to public in app settings or manifest before launching to external users.
- InfoRefresh Token 30-Minute Grace Period
Linear permits replaying refresh token requests within a 30-minute grace period to prevent race conditions during network failures.
Fix: Do not invalidate new refresh tokens immediately if a duplicate refresh request occurs within 30 minutes.
Why each scope
| Scope | Why you need it | Tier | Evidence |
|---|---|---|---|
read | Read issues, projects, cycles, and other workspace data on behalf of the authorizing entity. | basic | |
write | Create, update, and delete issues, projects, and cycles on behalf of the authorizing entity. | basic | |
issues:create | Scope restricted specifically to creating issues. | basic |
Reference facts
- Access Token Expiry24 hours (86,399 seconds)
- Refresh Token Grace Period30 minutes for request replay during network errors
- OAuth Request Rate Limit5,000 requests per hour per User (or App User)
- GraphQL Complexity Limit2,000,000 points per hour (max 10,000 points per query)
- Actor Modesactor=user (default) or actor=app
- Endpoints observed liveAuthorize: HTTP 200; serves an HTML login/consent page; → endpoint is live (client validation may happen after login) · Token: HTTP 400; error "invalid_client: Invalid client: client is invalid"; → token endpoint is live and rejects a bogus code
What we verified — and what we couldn't
Live probes (no credentials)
- ✓authorize
https://linear.app/oauth/authorizeHTTP 200; serves an HTML login/consent page; → endpoint is live (client validation may happen after login)[P1] - ✓token
https://api.linear.app/oauth/tokenHTTP 400; error "invalid_client: Invalid client: client is invalid"; → token endpoint is live and rejects a bogus code[P2] - ✓page
https://linear.app/settings/api/applications/newHTTP 200; title "Linear"[P3] - ✓page
https://linear.app/developers/oauth-2-0-authenticationHTTP 200[P4]
Open questions
- What is the typical review timeline for official Integration Directory submission?Linear documentation specifies required directory assets and eligibility criteria, but does not publish SLA or review turnaround times.To resolve: Contact integrations@linear.app or post in the Linear Slack community #api channel.
- Not searched: developer forums and community reportsThis key has no Google Search grounding, so only the provider's own pages were read. Real-world gotchas reported by developers may be missing.To resolve: Re-run with a billing-enabled Gemini key, or search the provider's community forum for review and rate-limit issues.
Ask the provider
A ready-to-send message built from the open questions above.
- Send to
- Linear Integrations Email & Slack Community
- Subject
- OAuth integration questions — Linear
Hi Linear developer support team, We're building an integration where create, read, update, and manage issues, projects, and cycles on behalf of the user. Before we register an OAuth app and launch to customers, we couldn't find answers to the following in your documentation: 1. What is the typical review timeline for official Integration Directory submission? (What we found: Linear documentation specifies required directory assets and eligibility criteria, but does not publish SLA or review turnaround times.) Could you point us to the right documentation or process — including whether any review or approval is needed before customers outside our own account can connect, and the typical timeline? Thanks, [Your name] [Company · website]
Sources
- S1OAuth 2.0 authentication – Linear Developersofficial
- S2OAuth application manifests – Linear Developersofficial
- S3OAuth actor authorization – Linear Developersofficial
- S4Rate limiting – Linear Developersofficial
- S5Integration Directory – Linear Developersofficial
- S6Linear – The system for product developmentofficial
- S7Linear – The system for product developmentofficial
- S8Linear Developersofficial
- P1Our probe: authorize check on linear.appprobe
- P2Our probe: token check on api.linear.appprobe
- P3Our probe: page check on linear.appprobe
- P4Our probe: page check on linear.appprobe