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.
Configure the redirect callback URLs to your application
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:
|
state | |
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:
|
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
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
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"
]
}
Once you have obtained a valid access token, you can make a request to Linear's GraphQL API.
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 } }" }' \
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 revoked400
- unable to revoke token (e.g. token was already revoked)401
- unable to authenticate with the token
Last modified 1yr ago