Linear Enterprise RBAC
Overview
Implement role-based access control for Linear integrations. Linear provides built-in organization roles (Owner, Admin, Member, Guest), team-level access control, and fine-grained OAuth scopes. Enterprise plans add SAML 2.0 SSO and SCIM user provisioning.
Prerequisites
- Linear Business or Enterprise plan (for SSO/SCIM)
- Organization admin access
- SSO provider (Okta, Azure AD, Google Workspace) for SAML
- Understanding of OAuth 2.0 scopes
Instructions
Step 1: Understand Linear's Built-In Roles
| Role | Capabilities |
|---|
| Owner | Full workspace control, billing, delete workspace |
| Admin | Manage members, teams, integrations, workspace settings |
| Member | Create/edit issues, access team-visible data |
| Guest | Read-only access to invited teams only |
These roles are fixed in Linear. Your application can layer additional permissions on top.
Step 2: Map Application Roles to OAuth Scopes
const ROLE_SCOPES: Record<string, string[]> = {
admin: ["read", "write", "issues:create", "admin"],
manager: ["read", "write", "issues:create"],
developer: ["read", "write", "issues:create"],
viewer: ["read"],
};
const TEAM_ACCESS: Record<string, "member" | "guest" | "none"> = {
admin: "member",
manager: "member",
developer: "member",
viewer: "guest",
};
Step 3: Permission Guard
import { LinearClient } from "@linear/sdk";
interface UserContext {
userId: string;
role: string;
linearClient: LinearClient;
teamIds: string[];
}
class PermissionGuard {
constructor(private ctx: UserContext) {}
canAccessTeam(teamId: string): boolean {
if (this.ctx.role === "admin") return true;
return this.ctx.teamIds.includes(teamId);
}
async canModifyIssue(issueId: string): Promise<boolean> {
if (this.ctx.role === "viewer") return false;
const issue = await this.ctx..(issueId);
team = issue.;
team ? .(team.) : ;
}
(): {
[, , ].(..);
}
(): {
.. === ;
}
(): {
.. === ;
}
(: []): {
(.. === ) ;
projectTeamIds.( ...(id));
}
}
() {
{
(!allowedRoles.(req..)) {
res.().({ : });
}
();
};
}
app.(, (, , ), createIssueHandler);
app.(, (), deleteIssueHandler);
app.(, (, , , ), listIssuesHandler);
Step 4: Scoped Client Factory
async function getClientForUser(userId: string): Promise<LinearClient> {
const token = await getStoredOAuthToken(userId);
if (!token) throw new Error("User not authenticated with Linear");
return new LinearClient({ accessToken: token });
}
async function getUserTeamIds(client: LinearClient): Promise<string[]> {
const viewer = await client.viewer;
const memberships = await viewer.teamMemberships();
const teamIds: string[] = [];
for (const membership of memberships.nodes) {
const team = await membership.team;
if (team) teamIds.push(team.id);
}
return teamIds;
}
Step 5: SAML SSO Configuration (Enterprise)
async function onSSOLogin(email: string): Promise<UserContext> {
const user = await db.users.findByEmail(email);
if (!user?.linearAccessToken) {
throw new Error("User must complete Linear OAuth after SSO login");
}
const client = new LinearClient({ accessToken: user.linearAccessToken });
const viewer = await client.viewer;
const teamIds = await getUserTeamIds(client);
return {
userId: user.id,
role: mapLinearRoleToAppRole(viewer),
linearClient: client,
teamIds,
};
}
function mapLinearRoleToAppRole(viewer: any): string {
if (viewer.admin) return "admin";
(viewer.) ;
;
}
Step 6: SCIM Provisioning (Enterprise)
async function syncSCIMUsers(client: LinearClient) {
const org = await client.organization;
const members = await org.users();
for (const user of members.nodes) {
console.log(`${user.name} (${user.email}): admin=${user.admin}, guest=${user.guest}, active=${user.active}`);
await db.users.upsert({
email: user.email,
name: user.name,
linearId: user.id,
role: user.admin ? "admin" : user.guest ? "viewer" : "developer",
active: user.active,
});
}
}
Step 7: Audit Logging
interface AuditEntry {
timestamp: string;
userId: string;
action: string;
resource: string;
resourceId: string;
details: Record<string, unknown>;
}
function logAudit(entry: AuditEntry): void {
console.log(JSON.stringify(entry));
}
async function auditedCreateIssue(
ctx: UserContext,
input: { teamId: string; title: string; [key: string]: any }
) {
const guard = new PermissionGuard(ctx);
if (!guard.canCreateIssue()) throw new Error("Forbidden");
if (!guard.canAccessTeam(input.teamId)) throw ();
result = ctx..(input);
({
: ().(),
: ctx.,
: ,
: ,
: ( result.)?. ?? ,
: { : input., : input. },
});
result;
}
() {
guard = (ctx);
(!( guard.(issueId))) ();
({
: ().(),
: ctx.,
: ,
: ,
: issueId,
: updates,
});
ctx..(issueId, updates);
}
Error Handling
| Error | Cause | Solution |
|---|
Forbidden | Token lacks required scope | Request OAuth with correct ROLE_SCOPES |
Authentication required | SSO session expired | Redirect to SAML IdP |
| SCIM sync fails | Invalid bearer token | Regenerate SCIM token in Linear admin |
| Guest can't create issue | Guest role is read-only | Upgrade to Member role in Linear |
| Team not accessible | User not added to team | Add user to team in Linear Settings |
Examples
List Organization Members by Role
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY! });
const org = await client.organization;
const members = await org.users();
for (const user of members.nodes) {
const role = user.admin ? "admin" : user.guest ? "guest" : "member";
console.log(`${user.name} (${user.email}): ${role}`);
}
Resources
