> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Admin

> Connect Linear with admin access so Serval can invite, suspend, and unsuspend users and manage workspace membership in your Linear organization.

## About Linear Admin

Linear Admin is the admin-scoped companion to the [Linear integration](/sections/integrations/linear). 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

| Capability                              | Description                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User provisioning via Access Management | Two 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 workflows      | Four 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 access           | The "Linear Admin API request" action gives workflows full admin-level access to Linear's GraphQL API, with authentication handled automatically.                                                                                                                                                                                                                                                                    |
| Connection health checks                | Three 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](https://linear.app/developers/graphql) can be accessed through Serval.

## Get your credentials

<Tabs>
  <Tab title="Sign in with Linear (Admin OAuth) - recommended">
    No Linear-side setup is needed. Serval's own Linear app handles the OAuth flow - you just approve it on Linear's consent screen.

    <Note>
      The person who authorizes the connection must be a **Linear workspace admin**. The connection requests admin access, and Linear only grants it if an admin approves.
    </Note>

    If this option is not shown in your environment (for example, on self-hosted deployments), use your own Linear OAuth app instead.
  </Tab>

  <Tab title="Use your own Linear OAuth app">
    You need a Linear OAuth application owned by your workspace, plus its Client ID and Client secret. The application needs no special admin configuration - admin access is requested when you authorize - but the person authorizing must be a workspace admin. See Linear's [OAuth 2.0 authentication guide](https://linear.app/developers/oauth-2-0-authentication) for background.

    <Steps>
      <Step title="Create or open a Linear OAuth application">
        In Linear, open **Settings**, then **API**, then **Applications**, and create a new OAuth application ([direct link](https://linear.app/settings/api/applications/new)), or open an existing one.
      </Step>

      <Step title="Register Serval's Callback URL">
        Copy the **Callback URL** shown in Serval's connect dialog (use the **Copy** button) and paste it into the application's **Callback URLs** list. Linear requires an exact match between this URL and the value Serval sends.
      </Step>

      <Step title="Copy the Client ID and Client secret">
        Save the application, then copy the **Client ID** and **Client secret** from the application's settings page.
      </Step>
    </Steps>

    <Warning>
      Linear shows the client secret **only once**, at creation. If you no longer have it, regenerate it from the application's settings page - and note that regenerating invalidates the old secret for any existing connections using it.
    </Warning>
  </Tab>
</Tabs>

## Connect in Serval

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

<Tabs>
  <Tab title="Sign in with Linear (Admin OAuth)">
    <Steps>
      <Step title="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."
      </Step>

      <Step title="Authorize in Linear">
        Approve the request on Linear's consent screen as a workspace admin. Serval is granted read, write, and admin access.
      </Step>

      <Step title="Done">
        Serval records your Linear organization's ID and name as the connected instance. The connection is workspace-wide.
      </Step>
    </Steps>

    <Note>
      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".
    </Note>
  </Tab>

  <Tab title="Use your own Linear OAuth app">
    <Steps>
      <Step title="Choose the bring-your-own option">
        Select **Use your own Linear OAuth app**: "Connect with an admin-capable Linear OAuth application owned by your workspace."
      </Step>

      <Step title="Copy the Callback URL">
        Under **1. Set up your Linear OAuth app**, use the **Copy** button (it toggles to **Copied**) next to the read-only **Callback URL** field, and paste the value verbatim into your Linear application's Callback URLs list.
      </Step>

      <Step title="Enter your app's credentials">
        Under **2. Enter your app's credentials**, fill in:

        * **Display name** (optional) - a friendly name shown in Serval, for example "My Company Linear Admin".
        * **Client ID** (required) - found on the application's settings page in Linear, under OAuth.
        * **Client secret** (required) - password field; Linear only shows this once when the app is created.

        The **Connect** button stays disabled until both Client ID and Client secret are filled in. If a blank value reaches the server anyway, the request is rejected and the dialog shows "Failed to initiate custom Linear admin app:" followed by "clientId is required" or "clientSecret is required".
      </Step>

      <Step title="Authorize in Linear">
        Click **Connect** and approve the request in Linear as a workspace admin. Complete the authorization within **10 minutes** - after that, the attempt fails with "Invalid or expired OAuth state" and you must submit the form again.
      </Step>
    </Steps>

    <Note>
      On reconnect, Serval opens directly on this form and prefills **Display name** and **Client ID**, but **Client secret** always starts blank and must be re-entered. Submitting re-runs the full Linear authorization.
    </Note>
  </Tab>
</Tabs>

## 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."

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Linear Admin and Linear are two separate connections - you likely need both">
    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.
  </Accordion>

  <Accordion title="A Linear workspace admin must authorize the connection">
    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.
  </Accordion>

  <Accordion title="Callback URL must match exactly">
    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.
  </Accordion>

  <Accordion title="Finish the bring-your-own authorization within 10 minutes">
    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.
  </Accordion>

  <Accordion title="Reconnect always requires re-entering the client secret">
    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.
  </Accordion>

  <Accordion title="Self-hosted and unconfigured environments: bring-your-own only">
    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."
  </Accordion>

  <Accordion title="Provisioning invites; deprovisioning suspends">
    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.
  </Accordion>

  <Accordion title="Client secret is shown once in Linear">
    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.
  </Accordion>

  <Accordion title="The connected instance is the Linear organization">
    After authorization, Serval records your Linear organization's ID and name as the connected instance. The connection is workspace-wide, not per-team.
  </Accordion>

  <Accordion title="Expired bring-your-own token with no refresh token">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Linear Admin integration.