Implement enterprise role-based access control with Linear.
Use when setting up team permissions, implementing SSO,
or managing access control for Linear integrations.
Trigger with phrases like "linear RBAC", "linear permissions",
"linear enterprise access", "linear SSO", "linear role management".
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
// Create Linear clients with appropriate access per user
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 });
}
// Verify team membership via API
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)
// Linear Enterprise supports SAML 2.0 SSO
// Configuration: Linear Settings > Security > SAML
// After SSO login, verify user's Linear access
async function onSSOLogin(email: string): Promise<UserContext> {
// Look up user's stored OAuth token
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";
if (viewer.guest) return "viewer";
return "developer";
}
Step 6: SCIM Provisioning (Enterprise)
// SCIM auto-syncs users and groups from your IdP to Linear
// Configuration: Linear Settings > Security > SCIM provisioning
// Endpoint: https://api.linear.app/scim/v2
// Bearer token: generated in Linear admin settings
// After SCIM syncs users, verify in your app
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}`);
// Sync to your app's user database
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 {
// Write to audit log (database, SIEM, CloudWatch, etc.)
console.log(JSON.stringify(entry));
}
// Wrap Linear operations with audit logging
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 new Error("No team access");
const result = await ctx.linearClient.createIssue(input);
logAudit({
timestamp: new Date().toISOString(),
userId: ctx.userId,
action: "issue.create",
resource: "Issue",
resourceId: (await result.issue)?.id ?? "",
details: { teamId: input.teamId, title: input.title },
});
return result;
}
async function auditedUpdateIssue(
ctx: UserContext,
issueId: string,
updates: Record<string, unknown>
) {
const guard = new PermissionGuard(ctx);
if (!(await guard.canModifyIssue(issueId))) throw new Error("Forbidden");
logAudit({
timestamp: new Date().toISOString(),
userId: ctx.userId,
action: "issue.update",
resource: "Issue",
resourceId: issueId,
details: updates,
});
return ctx.linearClient.updateIssue(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}`);
}
