OAuth actor authorization
By default all Linear’s API authentication methods treat the authenticating user as the API actor. This means that actions performed with the OAuth token will appear to come from that user, this is usually what you want!
Linear also supports an alternative authentication method with OAuth Actor Authorization – when authenticating this way the user will instead authorize installing the app within the workspace, actions performed with the received OAuth token will come from the app itself. This is particularly useful for agents and service accounts.
To enable the actor authorization, add actor=app parameter to your OAuth authorization URL. The setting is tied to the authorization and its access token. In this mode, all mutations such as creating issues, comments, and status changes will be performed by the app.
Token renewal
Using actor=app changes the identity that performs actions, not how tokens are renewed.
- Authorization-code grants: Use the refresh token to obtain a new access and refresh token pair.
- Client-credentials grants: No refresh token is issued. Request a new access token shortly before the current one expires.
See token lifetimes and renewal.
Changing an installation’s scopes
For authorization-code installations, repeat the authorization flow with update_scopes_on_existing_token=true. Request the complete scope set: all existing scopes plus any scopes being added. The update is subject to permission and team-access checks.
Exchanging the resulting authorization code replaces the installation’s access and refresh tokens, even if the scopes have not changed. Save the new pair and update every process that shares the installation’s credentials.
To remove scopes, revoke the existing authorization and authorize again with the reduced scope set. Repeating the ordinary installation flow without update_scopes_on_existing_token=true does not update an existing installation.
For client credentials, request a token with the new scope set. Adding or removing scopes revokes existing app-actor tokens for that app in the workspace. Processes sharing the app must use the same scope set to avoid invalidating each other’s tokens.
You can also add an optional user name and avatar to go with the application to have it rendered in User (via Application) format. This will help identify the user that performed the action in the 3rd party system that do not have a Linear account.
To set the custom user name, set the createAsUser attribute with the user name and set displayIconUrl with the URL of the avatar in issueCreate or commentCreate mutations:
mutation IssueCreate {
issueCreate(
input: {
title: "New exception"
description: "More detailed error report in markdown"
teamId: "9cfb482a-81e3-4154-b5b9-2c805e70a02d"
createAsUser: "Mark"
displayIconUrl: "http://path.to/image.png"
}
) {
success
issue {
id
title
}
}
}Note, 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.