Skip to main content

​
About Linear Admin

Linear Admin is the admin-scoped companion to the Linear integration. Linear does not allow the admin permission on the connection mode the ticket-sync Linear integration uses, so admin operations - inviting, suspending, and unsuspending users - live on this separate connection. Ticket syncing stays on the regular Linear connection; Linear Admin owns user provisioning and workspace-membership management. Workflow API requests are restricted to Linear’s API host, api.linear.app. Authentication: OAuth 2.0, either through the Serval-managed Linear app (“Sign in with Linear (Admin OAuth)”, recommended) or your own Linear OAuth application. Both request the read, write, and admin permissions, so a Linear workspace admin must authorize the connection. Data sync: No background or scheduled sync. Health checks, user-management workflows, provisioning, and API calls all run on demand. Access tokens are refreshed automatically whenever they are expired or within 5 minutes of expiry.

​
What the Linear Admin integration enables

CapabilityDescription
User provisioning via Access ManagementTwo app access roles are registered for Linear: Admin (organization administrator) and Member (standard member). Provisioning invites the requested user to your Linear organization with the mapped role - “Admin” grants Linear’s admin role, “Member” or “User” grants the standard member role. The user receives an invitation email from Linear and must accept it; accounts are not created directly.
User deprovisioning (suspend)Finds the target user by email (including already-suspended users) and suspends their Linear account. Deprovisioning suspends rather than deletes; a built-in unsuspend workflow can reactivate the account.
Built-in user-management workflowsFour admin workflows for use in any Serval workflow: “Get Linear User ID (Admin)”, “Invite Linear User (Admin)” (invites with the workspace default role), “Suspend Linear User (Admin)”, and “Unsuspend Linear User (Admin)”.
Admin-level Linear API accessThe “Linear Admin API request” action gives workflows full admin-level access to Linear’s GraphQL API, with authentication handled automatically.
Connection health checksThree read-only checks verify authentication, confirm admin access was actually granted, and confirm users (including suspended ones) can be listed.
Anything defined in the Linear GraphQL API can be accessed through Serval.

​
Get your credentials

​
Connect in Serval

When you connect Linear Admin, Serval shows a selection screen with two options.
1

Choose the managed option

Select Sign in with Linear (Admin OAuth) (marked Recommended): “Connect using the Serval-managed Linear admin OAuth app. You’ll be asked to grant admin access to your workspace.”
2

Authorize in Linear

Approve the request on Linear’s consent screen as a workspace admin. Serval is granted read, write, and admin access.
3

Done

Serval records your Linear organization’s ID and name as the connected instance. The connection is workspace-wide.
If this option is hidden, Serval-managed sign-in is not enabled for your deployment (self-hosted deployments hide it). If it is shown but the managed credentials are missing on the server, the connect dialog shows “Failed to initiate Linear Admin OAuth:” followed by “Linear Admin Serval-managed OAuth is not configured in this environment; connect a custom Linear OAuth app instead”.

​
Verifying the connection

Linear Admin ships three health checks that exercise the connection end to end: Test Linear Admin Connection - verifies the connection works and the OAuth token is valid by reading a single user.
  • Success: “Successfully authenticated with Linear (found [number] user)”
  • Failure: “Unable to authenticate with Linear. Please verify the Linear Admin connection is still active and the OAuth token has not been revoked.”
Verify Linear Admin Access - confirms admin access was actually granted by reading organization invites, the same capability user provisioning relies on. Unlike a plain read, this fails if the admin permission is missing.
  • Success: “Successfully verified Linear admin access (read organization invites)”
  • Failure: “Unable to read Linear organization invites. The connected Linear app may be missing the admin scope - reconnect and ensure a workspace admin grants admin access.”
List Linear Users (incl. suspended) - checks that Serval can list users including suspended ones, which is required to resolve a user before suspending them during deprovisioning.
  • Success: “Successfully listed Linear users including suspended (sample size: [number])”
  • Failure: “Unable to list users from Linear. Please verify the Linear Admin connection has not been disconnected.”
If “Test Linear Admin Connection” passes but “Verify Linear Admin Access” fails, the connection authenticated fine but was never granted admin access - usually because a non-admin authorized it. Reconnect and have a Linear workspace admin approve the consent screen.

​
Gotchas and troubleshooting

The ticket-sync Linear integration only requests read and write access, because the connection mode that attributes issues and comments to the original requester is incompatible with Linear’s admin permission. Linear Admin is the companion connection that carries admin access and owns user provisioning. Connect Linear for ticket syncing and issue workflows; connect Linear Admin for inviting, suspending, and unsuspending users.
Whoever clicks through Linear’s consent screen must be a workspace admin, or admin access is not actually granted. The connect dialog states this for the bring-your-own path: “The app must be authorized by a workspace admin so it can be granted admin access.” If a non-admin authorizes, plain authentication succeeds but the “Verify Linear Admin Access” health check fails with the missing-admin-scope message.
Linear rejects the connection if the Callback URL registered on your application differs at all from the one Serval uses. Always use the Copy button in Serval’s connect dialog and paste the value verbatim into Linear - a retyped or partial URL fails.
After you click Connect with your own app’s credentials, Serval holds them for 10 minutes while you authorize in Linear. If you take longer, the attempt fails with “Invalid or expired OAuth state” and you must submit the form again.
When reconnecting a bring-your-own connection, Display name and Client ID are prefilled, but the Client secret field is always blank and required - there is no leave-blank-to-keep-existing behavior. Submitting re-runs the full Linear authorization.
If Serval-managed sign-in is not enabled for your deployment, the “Sign in with Linear (Admin OAuth)” option is hidden; self-hosted deployments always use their own Linear OAuth app. If the option is shown but the managed credentials are not configured on the server, the attempt fails with: “Linear Admin Serval-managed OAuth is not configured in this environment; connect a custom Linear OAuth app instead.”
Provisioning sends a Linear organization invitation email - the user must accept it to join the workspace; nothing is created directly. Role names are strictly mapped: “Admin” grants Linear’s admin role, “Member” or “User” grants the standard member role, and any other role name fails the workflow with: Invalid role ‘[name]’. Must be one of: Admin, Member, or User. Deprovisioning suspends the account (found by email, including already-suspended users) rather than deleting it; the built-in unsuspend workflow can reactivate it.
Linear displays the OAuth client secret only at creation time. If it is lost, regenerate it on the application’s settings page - and note that the old secret stops working for any connection still using it.
After authorization, Serval records your Linear organization’s ID and name as the connected instance. The connection is workspace-wide, not per-team.
Tokens normally refresh automatically. If a bring-your-own token has expired and no refresh token is available, calls fail with “custom Linear admin app access token expired and no refresh token available; reconnect required” - reconnect the integration to fix it.
Need help? Contact support@serval.com for assistance with your Linear Admin integration.