Roles & Permissions

Control what users can do in your application with role-based access control.

Organization Roles

Every organization member has a role:

Owner

• Full control over the organization
• Manage billing and subscription
• Delete organization
• Cannot be removed

Admin

• Manage members and roles
• Configure organization settings
• Access all resources
• Can be removed by Owner

Member

• Access organization resources
• Limited permissions
• Can be removed by Admin or Owner

Guest

• Minimal access permissions
• Read-only access to shared resources
• Can be removed by Admin or Owner

Checking Permissions

Verify user roles in your application.

const session = await authClient.getSession()
 
if (session.user.role === 'owner') {
  // Owner-only actions
}
 
if (['owner', 'admin'].includes(session.user.role)) {
  // Admin actions
}

Managing Members

Invite Members

await authClient.organization.inviteMember({
  email: 'user@example.com',
  role: 'member'
})

Update Role

await authClient.organization.updateMember({
  userId: 'user-id',
  role: 'admin'
})

Remove Member

await authClient.organization.removeMember({
  userId: 'user-id'
})

Custom Permissions

Define custom permissions for your application.

const permissions = {
  'projects:read': ['owner', 'admin', 'member'],
  'projects:write': ['owner', 'admin'],
  'projects:delete': ['owner'],
  'billing:manage': ['owner']
}
 
function hasPermission(role: string, permission: string) {
  return permissions[permission]?.includes(role) ?? false
}

Role Claims in OIDC Tokens

When users authenticate via OAuth/OIDC, the ID token includes role and permission claims:

Token Claims

Example Token Payload

{
  "sub": "user_123",
  "organization_id": "org_456",
  "org_role": "admin",
  "org_permissions": ["tf:role:sales", "reports:view"],
  "licenses": ["tradeflow"],
  "entitlements": ["inventory:manage", "reports:export"]
}

Using Claims in Your App

import { jwtDecode } from 'jwt-decode';
 
const claims = jwtDecode(idToken);
 
// Check organization role
if (claims.org_role === 'admin') {
  // Show admin panel
}
 
// Check custom permissions
if (claims.org_permissions?.includes('tf:role:sales')) {
  // Show sales dashboard
}

Managing Custom Permissions

Assign custom permissions to users via the Portal UI:

1. Go to Team Members
2. Click on a member
3. In "Custom Permissions" card, add permissions like app:role:manager
4. Click Save Permissions

Best Practices

Principle of Least Privilege Grant users the minimum permissions needed.

Regular Audits Review member roles periodically.

Separate Concerns Use different roles for different responsibilities.

Document Permissions Keep clear documentation of what each role can do.

Next Steps

• Organizations - Organization management
• API Reference - API endpoints
• Security - Security guidelines