# Linear API keys (/integrations/linear-service-account)

Connect Linear with a personal API key. The key's permissions and team restrictions determine which operations and records the workflow can access.

Keys are bound to the user who creates them: every action a workflow takes is attributed to that user, and the key stops working if the user is deactivated or leaves the workspace. For production workflows, create the key from a dedicated service user (e.g. `sim-bot@yourcompany.com`) rather than a personal account.

## Prerequisites \[#prerequisites]

A Linear account that is allowed to create API keys. Workspace admins can disable API-key creation for members (**Settings** → **Administration** → **API** → **Member API keys**) — if the option is missing for you, ask an admin, or have an admin create the key (the restriction doesn't apply to admins).

## Create the API key \[#creating-the-api-key]

Log in as the service user, open Linear **Settings**, and go to **Account → Security & Access → Personal API keys**

Click **New API key** and give it a label (e.g. `Sim Integration`)

Choose the key's permissions. Grant **Read** for connection validation and add the write, administrative, or creation permissions required by your workflow. Restrict it to the teams the workflow needs; operations outside those teams will fail

Copy the key — it starts with `lin_api_` — and store it somewhere safe.

Warning:

The API key is limited by the creating user's access and any permissions or team restrictions selected for the key. Treat it like a password — do not commit it to source control or share it publicly. Sim encrypts the key at rest.

## Add the API key to Sim \[#adding-the-api-key-to-sim]

Open **Integrations** from your workspace sidebar

Search for "Linear" and open it, then click **Add to Sim** and choose **Add API key**

Paste the API key (`lin_api_...`) and optionally set a display name and description

Click **Add API key**. Sim verifies the key by querying Linear’s `viewer` and `organization` — if it fails, you'll see a specific error explaining what went wrong.

Warning:

The key must be able to read its own user to pass connection validation. Grant write permissions only for workflows that write, and include the teams those workflows need. Successful validation does not prove access to every operation.

## Use the credential in workflows \[#using-the-credential-in-workflows]

Add a Linear block to your workflow. In the credential dropdown, select the saved Linear API key. Configure the operation and its required fields.

The block calls Linear's GraphQL API (`api.linear.app/graphql`) with the key. Everything the workflow does — creating issues, adding comments, updating projects — is attributed to the user who created the key.

## Rotate keys and handle permission failures \[#rotate-keys-and-handle-permission-failures]

Personal API keys are tied to their creating user; a dedicated service user gives the workflow a stable attribution identity. The key identifies its workspace, so no workspace domain is required.

If connection validation succeeds but an operation fails, inspect the key’s permissions and team restrictions. Validation reads the authenticated user and organization; it does not prove access to writes or every team. Create a key with the required permissions, update the credential in Sim, and verify the failing operation.

Rotate by creating a replacement key, updating Sim, testing the workflow, and then deleting the old key. Keep the owning account active: deactivating or removing it can invalidate access. Review [Linear’s API-key permissions](https://linear.app/docs/api-and-webhooks) when granting or revoking keys.