Before You Begin

You will need:

• Admin access to Span (or the Integrations Admin role).

• A Linear user account with read access to every team whose work you want Span to analyze.

• A Linear personal API key (starts with lin_api_). OAuth tokens and OAuth app credentials will not work — see Personal API key vs. OAuth below.

The token's user only needs read access, and Span never writes to Linear. A regular user with broad permissions is fine — Span only ever reads. You do not need to create a dedicated read-only user.

Setup

Step 1 — Generate a Linear personal API key

1. In Linear, go to Settings → Account → Security & Access.

2. Under Personal API keys, click Create key.

3. Give it a descriptive label (e.g. Span Integration).

4. Set permissions to Read (or Full access). Span only reads data; extra write/admin scopes go unused.

5. Do not limit the key to specific teams unless you intentionally want Span to see only those teams. A team-restricted key will connect successfully but sync an incomplete dataset.

6. Copy the key — it starts with lin_api_ and Linear will not show it again.

If the Personal API keys section is missing, a workspace admin may have disabled member API keys under Settings → Administration → API → Member API keys. An admin can re-enable that setting, or an admin can create the key themselves.

Personal API key vs. OAuth. Linear's Settings → Administration → API page is for OAuth applications and workspace API-key policy — not for the credential Span uses. Create the key from your own account: Settings → Account → Security & Access. The key is tied to that user: it inherits their team access, and it stops working if that user is deactivated. For a long-lived integration, create the key from an account that will remain in the workspace (a dedicated Linear user is optional but recommended).

Step 2 — Connect Linear to Span

1. In Span, go to Settings → Tools & Integrations.

2. Select Linear.

3. Paste the personal API key into the API Key field.

Click Continue. Span verifies the key against Linear before saving the connection.

If validation fails, you will see "Invalid Linear API key". Typical causes:

What Data Span Syncs

No webhooks need to be configured on the Linear side. Span pulls data on a scheduled basis:

Linear issues are treated as a single "Task" type. Linear does not distinguish stories, bugs, and subtasks the way Jira does.

Metrics & Features Powered by Linear

With the Linear integration active, Span enables:

• Issue cycle time — time from start to completion (with percentile analysis).

• Issue lifetime — total time from creation to completion.

• Completed and open issue volume.

• Work allocation — investment mix via Linear initiatives, projects, and issue activity, correlated with pull requests and other sources.

Known Limitations

• Issue SLA metrics are not available — SLA tracking requires Jira-specific features.

• Issue subtype metrics (for example "Done Stories" or "Done Bugs") are not available, because Linear uses a single issue type.

Troubleshooting