Connecting to Linear

You can authenticate to Linear with a personal API key or with OAuth 2.0.

• API Key: The simplest option. Use it to connect with your own Linear account.
• OAuth (authorization code): Authenticate an application on behalf of a Linear user. Set AuthScheme to OAuth.
• OAuth (client credentials): Authenticate the application itself, for app-owned (machine-to-machine) access with no user interaction. Set AuthScheme to OAuthClient.

Authenticate with an API Key

To connect with a personal API key, set the following:

• AuthScheme: APIKey.
• APIKey: A Linear personal API key.

To create a personal API key:

1. Log in to Linear and open Settings > Security & access > Personal API keys.
2. Select New API key, name it, and create it.
3. Copy the key immediately. Linear shows it only once.

Authenticate with OAuth

The provider supports the OAuth 2.0 authorization code grant. All OAuth flows require a custom OAuth application registered in Linear.

See Creating a Custom OAuth Application for the steps to create one.

Client Credentials

Use the client credentials grant to authenticate the application itself, with no user sign-in. This is suited to backend or machine-to-machine integrations that act as the OAuth application rather than on behalf of a specific user.

Set the following and connect:

• AuthScheme: OAuthClient.
• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.

Note: To request specific OAuth scopes, set Scope to a comma-separated list (for example, read,write). When omitted, the provider requests read,write. Scope is optional and is not a standard connection property.

No browser interaction or callback URL is required. The provider obtains an access token directly from the Linear token endpoint and refreshes it automatically.

Desktop Applications

After registering a custom OAuth application, set the following and connect:

• InitiateOAuth: GETANDREFRESH. Use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.
• CallbackURL: The Callback URL defined in your OAuth application (for example, http://localhost:33333).

Note: To request specific OAuth scopes, set Scope to a comma-separated list (for example, read,write). When omitted, the provider requests read,write. Scope is optional and is not a standard connection property.

When you connect, the provider opens Linear's OAuth endpoint in your default browser. Log in and grant access to the application. The provider then completes the OAuth process:

1. The provider obtains an access token from Linear and uses it to request data.
2. The OAuth values are saved in the location specified by OAuthSettingsLocation and persist across connections.

The provider refreshes the access token automatically when it expires.

Web Applications

To connect from a web application, use the provider to obtain and manage the OAuth token values.

Get an OAuth Access Token

Set the following connection properties:

• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.

Then call stored procedures to complete the OAuth exchange:

1. Call the GetOAuthAuthorizationURL stored procedure. Set the CallbackURL to the redirect URI registered with your OAuth application. The procedure returns the URL to the Linear authorization endpoint.
2. Open the returned URL in a browser. Log in and authorize the application. Linear redirects to your callback URL with a code parameter appended.
3. Call the GetOAuthAccessToken stored procedure. Set the Verifier input to the code value from the redirect, and CallbackURL to the same redirect URI.

After you obtain the access and refresh tokens, set the following to connect and refresh the token automatically:

• InitiateOAuth: REFRESH.
• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.
• OAuthAccessToken: The access token returned by GetOAuthAccessToken.
• OAuthSettingsLocation: A writable path where the provider persists the OAuth values across connections.

Headless Machines

To authenticate on a machine without a browser, obtain the OAuth values on another machine that has a browser and transfer them.

1. On a machine with a browser, register the custom OAuth application and complete a desktop or web flow to obtain an OAuthAccessToken and OAuthRefreshToken (or an OAuthVerifier).
2. On the headless machine, set InitiateOAuth to REFRESH, supply OAuthClientId, OAuthClientSecret, the token values, and OAuthSettingsLocation. The provider then refreshes the access token automatically.