LinearChangelogDocumentation
Search
⌃K
Links

OAuth 2.0 Authentication

How to quickly get a Linear OAuth application set up.
Linear supports OAuth2 authentication, which is recommended if you're building applications to integrate with Linear.
It is highly recommended you create a workspace for the purpose of managing the OAuth2 Application, as each admin user will have access.

1. Create an OAuth2 application in Linear

Create a new OAuth2 Application​
Configure the redirect callback URLs to your application

2. Redirect user access requests to Linear

When authorizing a user to the Linear API, redirect to an authorization URL with correct parameters and scopes:
GET https://linear.app/oauth/authorize
Parameters
Name
Description
client_id
(required) Client ID provided when you create the OAuth2 Application
redirect_uri
(required) Redirect URI
response_type=code
(required) Expected response type
scope
(required) Comma separated list of scopes:
  • read - (Default) Read access for the user's account. This scope will always be present.
  • write - Write access for the user's account. If your application only needs to create comments, use a more targeted scope
  • issues:create - Allows creating new issues and their attachments
  • comments:create - Allows creating new issue comments
  • admin - Full access to admin level endpoints. You should never ask for this permission unless it's absolutely needed
state
(optional) Prevents CSRF attacks and should always be supplied. Read more about it here​
prompt=consent
(optional) The consent screen is displayed every time, even if all scopes were previously granted. This can be useful if you want to give users the opportunity to connect multiple workspaces.
actor
Define how the OAuth application should create issues, comments and other changes:
  • user - (Default) Resources are created as the user who authorized the application. This option should be used if you want each user to do their own authentication
  • application - Resources are created as the application. This option should be used if you have have only one user (e.g. admin) authorizing the application. Can be used together with createAsUser property when creating issues and comments.
Example
GET https://linear.app/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&state=SECURE_RANDOM&scope=read
​
GET https://linear.app/oauth/authorize?client_id=client1&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Foauth%2Fcallback&response_type=code&scope=read,write

3. Handle the redirect URLs you specified in the OAuth2 Application

Once the user approves your application they will be redirected back to your application, with the OAuth authorization code in the URL params.
Any state parameter you specified in step 2 will also be returned in the URL params and must match the value specified in step 2. If the values do not match, the request should not be trusted.
Example
GET https://example.com/oauth/callback?code=9a5190f637d8b1ad0ca92ab3ec4c0d033ad6c862&state=b1ad0ca92

4. Exchange code for an access token

After receiving the code, you can exchange it for a Linear API access token:
POST https://api.linear.app/oauth/token
Content-Type header should be application/x-www-form-urlencoded
Parameters
Name
Description
code
(required) Authorization code from the previous step
redirect_uri
(required) Same redirect URI which you used in the previous step
client_id
(required) Application's client ID
client_secret
(required) Application's client secret
grant_type=authorization_code
(required)
Response
After a successful request, a valid access token will be returned in the response:
{
"access_token": "00a21d8b0c4e2375114e49c067dfb81eb0d2076f48354714cd5df984d87b67cc",
"token_type": "Bearer",
"expires_in": 315705599,
"scope": [
"read",
"write"
]
}

5. Make an API request

Once you have obtained a valid access token, you can make a request to Linear's GraphQL API.
You can initialize the Linear Client with the access token:
const client = new LinearClient({ accessToken: response.access_token })
const me = await client.viewer
Or pass the token as an authorization header:
curl https://api.linear.app/graphql \
-X POST \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer 00a21d8b0c4e2375114e49c067dfb81eb0d2076f48354714cd5df984d87b67cc' \
--data '{ "query": "{ viewer { id name } }" }' \

6. Revoke an access token

To revoke a user's access to your application pass the access token as Bearer token in the authorization header (Authorization: Bearer <ACCESS_TOKEN>) or as the access_token form field:
POST https://api.linear.app/oauth/revoke
Response
Expected HTTP status:
  • 200 - token was revoked
  • 400 - unable to revoke token (e.g. token was already revoked)
  • 401 - unable to authenticate with the token
GraphQL API - Previous
Attachments
Next - OAuth 2.0
OAuth Actor Authorization
Last modified 1yr ago