← All guides

Linear

Routes

Steps — who does what

1. Create a dedicated workspace for the OAuth app You

   Needs you because: developer decision

   • Linear recommends a dedicated workspace because every admin user of it gets access to the OAuth app.
   • Decide which workspace will own the app before you register anything.

   Expected: A workspace you are willing to give admin access to for the app.

   ~10 min · Agent has not attempted this step c2

2. Sign in to Linear and open the app creation form You

   Needs you because: login or mfa

   • Sign in to the workspace from step 1.
   • Open the new OAuth application form.

   https://linear.app/settings/api/applications/new

   Expected: The OAuth application creation form is shown.

   ~5 min · Agent has not attempted this step c4c3

3. Fill in app identity fields Agent or you
   • Client name: 2-80 characters, must not contain "Linear", http:// or https://.
   • Developer name: 2-80 characters.
   • Client URI: absolute http or https URL.
   • Display description: up to 1000 characters.

   Client nameYOUR-APP-NAME

   Client URIhttps://YOUR-APP.example

   Display descriptionShort description of what your agent does in Linear (max 1000 chars).

   Expected: Identity fields accepted by the form.

   ~10 min · Agent has not attempted this step c32c33c34c35

4. Add redirect callback URLs Agent or you
   • Add at least one and at most 32 redirect URIs.
   • Each must be an absolute http or https URL.
   • Keep the exact string you register; the token exchange must send the same redirect_uri.

   Redirect URIhttps://YOUR-APP.example/oauth/callback

   Expected: Redirect URIs saved on the app.

   ~10 min · Agent has not attempted this step c18c19c20

5. Choose the distribution setting You

   Needs you because: developer decision

   • Distribution controls whether the app works only in the current workspace or can be installed by other workspaces.
   • It defaults to private; switch it to installable only if users in other workspaces must connect.

   Expected: Distribution set to private or installable to match your product.

   ~5 min · Agent has not attempted this step c5c6

6. Decide on client credentials tokens You

   Needs you because: developer decision

   • Client credentials tokens are for server-to-server apps that cannot run a user-initiated flow with refresh tokens.
   • They must be toggled on for the app when creating or editing it.
   • Skip this if your agent always acts on behalf of a signed-in user.

   Expected: Client credentials toggle set as intended.

   ~5 min · Agent has not attempted this step c9c10c7

7. Save the app and copy the client ID and secret Agent or you
   • Submit the form to create the OAuth2 application.
   • Store the client ID and client secret in your secret manager; the secret can be rotated later without re-registering the app.

   Expected: An OAuth2 app exists with credentials you can use.

   ~5 min · Agent has not attempted this step c3c31

8. Make the app installable by other workspaces You

   Only for: Installable app (other workspaces can install it)

   Needs you because: developer decision

   • Set distribution so the app is available to workspaces other than the one that created it.
   • The docs we read describe no review, listing or approval step for this; treat that as unconfirmed.

   Expected: App can be installed from other workspaces.

   ~5 min · Agent has not attempted this step c5c45

If you get stuck

Gotchas

• Access tokens last 24 hours and must be refreshed; the token response includes a refresh token. c21c22
• Refresh requests have a 30-minute grace period, so a failed refresh can be replayed. c23
• Client credentials tokens are app actor tokens valid 30 days, cover all public teams, and have no refresh token; fetch a new one after a 401. c25c26
• Up to 1000 client credentials tokens can be active in parallel only if they use the same scopes. c27
• Rotating the client secret kills client credentials tokens but does not revoke access or refresh tokens already granted to workspaces. c29c30
• read is the default scope and always present; prefer targeted scopes and request admin only when necessary. c13c14c15
• Scopes go in the authorization request as a comma-separated list. c16
• actor=app makes token actions come from the app itself, which suits agents; actor=application is deprecated. c11c12
• Agent scopes such as app:assignable and app:mentionable are documented under App authentication. c17
• The authorization request needs code_challenge_method plain or S256; send state to guard against CSRF. c41c40
• prompt=consent forces the consent screen every time. c42
• App creation can be pre-filled with URL parameters or a JSON manifest (schema 1.0.0); the manifest wins if both are given. c37c38c39
• No OAuth metadata is published at /.well-known/oauth-authorization-server or /.well-known/openid-configuration on linear.app. c49c50

OAuth configuration

Authorization URL

https://linear.app/oauth/authorize

Token URL

https://api.linear.app/oauth/token

Grant types

authorization_code, client_credentials

PKCE

required

Redirect URIs

• At least 1 and at most 32 redirect URIs
• Must be absolute http or https URLs
• redirect_uri at token exchange must match the one used in authorization

Token lifetimes

Access: 24 hours (authorization_code); 30 days (client_credentials); refresh: unknown. Refresh requests have a 30-minute grace period; client credentials tokens have no refresh token.

App types

• OAuth2 application (Linear recommends OAuth2 for integrations)

What we tested, and what we couldn't

Depth reached: endpoint probes

Live generation reads public documentation and sends unauthenticated requests only. It does not sign in, create an app, or submit anything.

Not attempted

• Signing in to the developer console
• Creating a test app
• Submitting an app for review

Open questions

• Does Linear review or approve an app before other workspaces can install it? The pages we read describe no review process, but that is absence of evidence.
  Check the Linear developer docs for an app listing or review page, or ask Linear support.
• Are there requirements on the client URI or redirect URIs beyond being absolute HTTP/HTTPS URLs, such as verified domains or published privacy/terms pages?
  Read the full OAuth app settings reference in Linear's developer docs.
• Is a paid Linear plan needed to create or distribute an OAuth app? No fee or plan requirement appears in the pages read.
  Try creating an app on a free workspace, or check Linear's pricing and developer docs.
• What exactly does the developer console show when signed out? A signed-out request returned HTTP 200 without a clear sign-in wall.
  Open https://linear.app/settings/api/applications/new in a private browser window and observe the redirect or sign-in prompt.
• Do the console steps match what the developer console actually shows today?
  This guide came from documentation and unauthenticated endpoint checks. Nobody signed in or created an app, so click-by-click steps are documented, not observed.

Evidence

53 claims behind this guide.

• c1 Official docs high confidence
  Linear recommends OAuth2 authentication for applications built to integrate with Linear.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  Linear supports OAuth2 authentication, which is recommended if you’re building applications to integrate with Linear.
• c2 Official docs high confidence
  Linear highly recommends creating a dedicated workspace for managing the OAuth2 application, because each admin user will have access to it.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  It is highly recommended you create a workspace for the purpose of managing the OAuth2 Application, as each admin user will have access.
• c3 Official docs high confidence
  Creating a Linear OAuth2 application is done by creating a new OAuth2 Application and configuring its redirect callback URLs.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  Create a new OAuth2 Application and configure the redirect callback URLs to your application.
• c4 Official docs high confidence
  Linear's OAuth app creation form is at https://linear.app/settings/api/applications/new.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  https://linear.app/settings/api/applications/new
• c5 Official docs high confidence
  A Linear OAuth app's distribution setting determines whether it is available only in the current workspace or installable by other workspaces.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  Whether the app should be available only in the current workspace or installable by other workspaces.
• c6 Official docs high confidence
  The Linear OAuth app distribution setting defaults to private.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  Allowed values: private , public Default: private
• c7 Official docs high confidence
  Linear OAuth apps support two grant types: authorization_code and client_credentials.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  Allowed values: authorization_code , client_credentials
• c8 Official docs high confidence
  For Linear OAuth apps, the authorization_code grant type is always required.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  authorization_code is always required
• c9 Official docs high confidence
  Client credentials tokens are intended for OAuth2 apps doing server-to-server communication that cannot support a user-initiated OAuth flow with refresh tokens.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  grant type for OAuth2 apps that use tokens for server-to-server communication and cannot support a user-initiated OAuth flow involving refresh tokens.
• c10 Official docs high confidence
  To use client credentials tokens, the developer must first toggle on client credentials tokens for the OAuth2 app when creating or editing it in Linear.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  You must first toggle on client credentials tokens for your OAuth2 app when creating or editing the app in Linear
• c11 Official docs high confidence
  Adding actor=app to the Linear OAuth authorization URL makes actions performed with the token come from the app itself, which is useful for agents and service accounts.
  OAuth actor authorization – Linear Developers retrieved 2026-10-27
  To enable the actor authorization, add actor=app parameter to your OAuth authorization URL
• c12 Official docs high confidence
  Linear's actor=application mode was deprecated in favor of actor=app, though apps already using it can continue to do so.
  OAuth actor authorization – Linear Developers retrieved 2026-10-27
  we previously supported a similar actor=application as a mode – this was deprecated in favor of the behavior in actor=app . If your app already uses this option then you can continue to do so.
• c13 Official docs high confidence
  The read scope is the default Linear OAuth scope and is always present.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  read - (Default) Read access for the user’s account. This scope will always be present.
• c14 Official docs high confidence
  Linear advises using a more targeted scope such as issues:create if the application only needs to create comments.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  If your application only needs to create comments, use a more targeted scope issues:create
• c15 Official docs high confidence
  Linear's admin scope grants full access to admin-level endpoints and should only be requested when absolutely needed.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  admin - Full access to admin level endpoints. You should never ask for this permission unless it’s absolutely needed
• c16 Official docs high confidence
  Linear OAuth scopes are passed as a comma-separated list in the authorization request.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  scope | (required) Comma separated list of scopes
• c17 Official docs high confidence
  Agent-specific Linear scopes such as app:assignable or app:mentionable are documented under App authentication.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  See App authentication for agent-specific scopes such as app:assignable or app:mentionable .
• c18 Official docs high confidence
  A Linear OAuth app must have at least one redirect URI and can have at most 32.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  oauth.redirect_uris Type: string[] Required: yes Minimum items: 1 Maximum items: 32 Values must be unique
• c19 Official docs high confidence
  Linear OAuth redirect URIs must be absolute HTTP or HTTPS URLs.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  A redirect URI registered for the OAuth app. Repeat this parameter to provide multiple values. Format: absolute HTTP or HTTPS URL
• c20 Official docs high confidence
  When exchanging a Linear authorization code for a token, the redirect_uri must be the same one used in the authorization step.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  redirect_uri | (required) Same redirect URI which you used in the previous step
• c21 Official docs high confidence
  Linear OAuth access tokens are valid for 24 hours and must be refreshed when they expire.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  The access token is valid for 24 hours and will need to be refreshed when it expires.
• c22 Official docs high confidence
  A successful Linear token exchange returns both an access token and a refresh token.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  After a successful request, a valid access token and refresh token will be returned in the response.
• c23 Official docs high confidence
  Linear refresh token requests have a 30-minute grace period so the original request can be replayed to retrieve the new refresh token after network errors.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  Requests to consume a refresh token and obtain a new one have a 30-minute grace period to allow for network errors.
• c24 Official docs high confidence
  All Linear OAuth2 applications were migrated to the new refresh token system on April 1, 2026.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  All OAuth2 applications were migrated to the new refresh token system on April 1, 2026.
• c25 Official docs high confidence
  A Linear client credentials token is an app actor token with access to all public teams in the workspace and is valid for 30 days.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  The token generated using this grant type will be an actor token that has access to all public teams in the workspace and is valid for 30 days.
• c26 Official docs high confidence
  Client credentials tokens have no refresh token, so the server is expected to fetch a new token after a 401 error.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  Since there is no refresh token paired with this access token, your server is expected to fetch a new token if it receives a 401 error when making a request with the previous token.
• c27 Official docs high confidence
  A Linear OAuth2 app can hold up to 1000 active client credentials tokens in parallel, provided each token uses the same scopes.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  OAuth2 apps can have up to 1000 active client credentials tokens in parallel, provided each token uses the same scopes.
• c28 Official docs high confidence
  Requesting a Linear client credentials token with different scopes revokes all existing app actor tokens and replaces them with the new token.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  If you request a client credentials token with different scopes, all existing actor tokens for the app are revoked and replaced with the new token carrying the updated scopes.
• c29 Official docs high confidence
  Rotating a Linear OAuth app's client secret immediately invalidates any client credentials tokens issued for the application.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  Rotating your client secret immediately invalidates any client credentials tokens issued for your application.
• c30 Official docs high confidence
  Rotating a Linear client secret does not revoke access or refresh tokens already granted to individual workspaces.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  It does not revoke access or refresh tokens already granted to individual workspaces — those keep working, and will use your new secret the next time they’re refreshed.
• c31 Official docs high confidence
  A Linear OAuth app's client secret can be rotated without re-registering the application.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  you can generate a new client secret or webhook signing secret without re-registering your application.
• c32 Official docs high confidence
  Linear OAuth app client names must be 2 to 80 characters and must not contain "Linear" or http:// or https://.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  oauth.client_name Type: string Required: yes Min length: 2 Max length: 80 Must not contain Linear Must not contain http:// or https://
• c33 Official docs high confidence
  A Linear OAuth app requires a developer name of 2 to 80 characters.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  developer.name Type: string Required: yes Min length: 2 Max length: 80
• c34 Official docs high confidence
  A Linear OAuth app requires a client URI that is an absolute HTTP or HTTPS URL.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  oauth.client_uri Type: string Required: yes Format: absolute HTTP or HTTPS URL
• c35 Official docs high confidence
  A Linear OAuth app's display description has a maximum length of 1000 characters.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  display.description Type: string Max length: 1000 characters
• c36 Official docs high confidence
  Linear webhook URLs for OAuth apps must use https:// and must not point to a loopback host, private-network host, or linear.app.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  Must use https:// The host must not be a loopback host, private-network host, or linear.app
• c37 Official docs high confidence
  Linear OAuth app configuration can be pre-populated via URL parameters on the app creation page or via a JSON manifest.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  OAuth app manifests let developers define a Linear OAuth app as structured data instead of filling the form manually.
• c38 Official docs high confidence
  If both dot-notation URL parameters and a manifest query parameter are supplied to Linear's app creation page, the JSON manifest takes precedence.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  If both dot-notation parameters and a manifest query parameter are provided, the JSON manifest takes precedence.
• c39 Official docs high confidence
  Linear's OAuth app manifest schema version is currently 1.0.0.
  OAuth application manifests – Linear Developers retrieved 2026-10-27
  schemaVersion ⁠ The version of the OAuth app manifest format. Type: string Required: yes Current value: 1.0.0
• c40 Official docs high confidence
  Linear recommends supplying the optional state parameter to prevent CSRF attacks.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  state | (optional, recommended ) Prevents CSRF attacks and should always be supplied.
• c41 Official docs high confidence
  Linear's authorization request requires a code_challenge_method of either plain or S256.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  code_challenge_method | (required) Either plain or S256 , depending on whether the challenge is the plain verifier string or the SHA256 hash of the string
• c42 Official docs high confidence
  Linear's prompt=consent parameter makes the consent screen display every time, even if all scopes were previously granted.
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  prompt=consent | (optional) The consent screen is displayed every time, even if all scopes were previously granted.
• c43 Official docs high confidence
  Linear documents OAuth 2.0 and personal API keys as the two ways to authenticate requests to the Linear API.
  Linear Developers retrieved 2026-10-27
  Use OAuth 2.0 or personal API keys to authenticate your requests to the Linear API
• c44 Official docs high confidence
  Linear's developer documentation lists an Agents guide for integrating an AI agent into Linear.
  Linear Developers retrieved 2026-10-27
  Agents How to best integrate an AI agent into Linear
• c45 Inferred medium confidence
  None of the 6 official pages read mentions an app review, approval or listing-review process. This is absence of evidence in the pages we read, not confirmation that no such requirement exists.
  Linear Developers retrieved 2026-10-27
  Linear – The system for product development retrieved 2026-10-27
  Linear – Agents that follow work from conversation to code retrieved 2026-10-27
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  OAuth actor authorization – Linear Developers retrieved 2026-10-27
  OAuth application manifests – Linear Developers retrieved 2026-10-27
• c46 Inferred medium confidence
  None of the 6 official pages read mentions business, identity or publisher verification. This is absence of evidence in the pages we read, not confirmation that no such requirement exists.
  Linear Developers retrieved 2026-10-27
  Linear – The system for product development retrieved 2026-10-27
  Linear – Agents that follow work from conversation to code retrieved 2026-10-27
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  OAuth actor authorization – Linear Developers retrieved 2026-10-27
  OAuth application manifests – Linear Developers retrieved 2026-10-27
• c47 Inferred medium confidence
  None of the 6 official pages read mentions a security assessment or audit. This is absence of evidence in the pages we read, not confirmation that no such requirement exists.
  Linear Developers retrieved 2026-10-27
  Linear – The system for product development retrieved 2026-10-27
  Linear – Agents that follow work from conversation to code retrieved 2026-10-27
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  OAuth actor authorization – Linear Developers retrieved 2026-10-27
  OAuth application manifests – Linear Developers retrieved 2026-10-27
• c48 Inferred medium confidence
  None of the 6 official pages read mentions a paid plan, fee or subscription requirement. This is absence of evidence in the pages we read, not confirmation that no such requirement exists.
  Linear Developers retrieved 2026-10-27
  Linear – The system for product development retrieved 2026-10-27
  Linear – Agents that follow work from conversation to code retrieved 2026-10-27
  OAuth 2.0 authentication – Linear Developers retrieved 2026-10-27
  OAuth actor authorization – Linear Developers retrieved 2026-10-27
  OAuth application manifests – Linear Developers retrieved 2026-10-27
• c49 Tested high confidence
  GET /.well-known/oauth-authorization-server on linear.app returned HTTP 404, so no OAuth metadata is published at this path
  Direct request by the agent retrieved 2026-10-27
• c50 Tested high confidence
  GET /.well-known/openid-configuration on linear.app returned HTTP 404, so no OAuth metadata is published at this path
  Direct request by the agent retrieved 2026-10-27
• c51 Tested high confidence
  Calling the authorization endpoint with an unregistered client_id returned HTTP 200, page title 'Linear'.
  Direct request by the agent retrieved 2026-10-27
• c52 Tested high confidence
  Posting fake client credentials to the token endpoint returned HTTP 400, error code 'invalid_client'.
  Direct request by the agent retrieved 2026-10-27
• c53 Tested medium confidence
  Opening the developer console URL while signed out returned HTTP 200, which does not clearly show a sign-in wall.
  Direct request by the agent retrieved 2026-10-27

Last verified 2026-10-27; recheck after 2027-01-25. Generated by deepseek-chat / pipeline v0.1 · raw JSON