Roles & Permissions

Control what team members can do in your organization with role-based access control.

Overview

LinkForty uses role-based access control (RBAC) to manage permissions. Each organization member has a role that determines their capabilities.

Available Roles:

• Owner - Full control (1 per organization)
• Admin - Manage settings and members
• Member - Create and manage links
• Viewer - Read-only access

Role Comparison

Permission	Owner	Admin	Member	Viewer
Links
View links	✅	✅	✅	✅
Create links	✅	✅	✅	❌
Edit links	✅	✅	✅	❌
Delete links	✅	✅	✅	❌
Bulk operations	✅	✅	✅	❌
Analytics
View analytics	✅	✅	✅	✅
Export data	✅	✅	✅	❌
Projects
View projects	✅	✅	✅	✅
Create projects	✅	✅	✅	❌
Edit projects	✅	✅	✅	❌
Delete projects	✅	✅	❌	❌
Team
View members	✅	✅	✅	✅
Invite members	✅	✅	❌	❌
Remove members	✅	✅	❌	❌
Change roles	✅	✅*	❌	❌
Organization
View settings	✅	✅	✅	✅
Edit settings	✅	✅	❌	❌
Manage billing	✅	❌	❌	❌
Delete organization	✅	❌	❌	❌
Webhooks
View webhooks	✅	✅	✅	✅
Create webhooks	✅	✅	❌	❌
Edit webhooks	✅	✅	❌	❌
Delete webhooks	✅	✅	❌	❌
Custom Domains
View domains	✅	✅	✅	✅
Add domains	✅	✅	❌	❌
Remove domains	✅	✅	❌	❌
API Keys
View API keys	✅	✅	✅	❌
Create API keys	✅	✅	❌	❌
Delete API keys	✅	✅	❌	❌

* Admins can't promote members to Owner

Role Descriptions

Owner

The organization creator with full control.

Unique Abilities:

• Delete organization
• Manage billing and subscriptions
• Transfer ownership
• Cannot be removed (must transfer ownership first)

Limitations:

• Only 1 owner per organization
• Cannot leave without transferring ownership or deleting org

Use Case: Founder, company owner, billing administrator

Admin

Trusted team leads who manage the organization.

Can Do:

• Manage all settings
• Invite and remove members
• Create and manage resources
• Change member roles (except Owner)

Cannot Do:

• Delete organization
• Manage billing
• Promote to Owner

Use Case: Team leads, managers, senior staff

Member

Regular team members who work with links.

Can Do:

• Create and manage links
• View analytics
• Work with projects
• Export data

Cannot Do:

• Invite team members
• Change settings
• Manage billing
• Delete organization

Use Case: Marketing team, content creators, developers

Viewer

Read-only access for stakeholders.

Can Do:

• View links
• View analytics
• View projects
• View team members

Cannot Do:

• Create or edit anything
• Export data
• Invite members

Use Case: Clients, stakeholders, auditors, interns

Managing Roles

Viewing Member Roles

Dashboard:

1. Go to Settings → Team
2. See all members with their roles

API:

curl https://api.linkforty.com/api/organizations/org_abc123/members \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Response:

[
  {
    "id": "member_1",
    "user_id": "user_123",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "owner",
    "status": "active",
    "joined_at": "2024-01-15T10:00:00Z"
  },
  {
    "id": "member_2",
    "user_id": "user_456",
    "name": "Sarah Smith",
    "email": "sarah@example.com",
    "role": "admin",
    "status": "active",
    "joined_at": "2024-02-20T14:30:00Z"
  }
]

Changing Member Roles

Dashboard:

1. Go to Settings → Team
2. Click member's role dropdown
3. Select new role
4. Click "Save"

API:

curl -X PUT https://api.linkforty.com/api/organizations/org_abc123/members/user_456 \
  -H "Authorization: Bearer $LINKFORTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "member"
  }'

Requires: Owner or Admin role

Restrictions:

• Admins cannot promote anyone to Owner
• Cannot change Owner role (must transfer ownership)
• Cannot change your own role to a lower permission level

Transferring Ownership

Only the current owner can transfer ownership.

Dashboard:

1. Go to Settings → Organization
2. Scroll to "Transfer Ownership"
3. Select new owner (must be existing member)
4. Click "Transfer"
5. Confirm transfer

API:

curl -X POST https://api.linkforty.com/api/organizations/org_abc123/transfer-ownership \
  -H "Authorization: Bearer $LINKFORTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "newOwnerId": "user_789"
  }'

What Happens:

1. New owner gets Owner role
2. Previous owner becomes Admin
3. Billing transfers to new owner
4. Can't be undone (new owner must transfer back)

Permission Enforcement

API Level

All API endpoints check permissions:

// Requires Owner role
fastify.delete('/api/organizations/:id', {
  preHandler: [authenticate, requireRole('owner')],
  handler: async (request, reply) => {
    // Delete organization
  }
});

// Requires Admin or Owner
fastify.put('/api/organizations/:id', {
  preHandler: [authenticate, requireRole('admin')],
  handler: async (request, reply) => {
    // Update organization
  }
});

Dashboard Level

UI elements hidden based on role:

{user.role === 'owner' && (
  <button onClick={deleteOrganization}>
    Delete Organization
  </button>
)}

{['owner', 'admin'].includes(user.role) && (
  <button onClick={inviteMember}>
    Invite Member
  </button>
)}

Common Scenarios

1. Small Team (2-5 people)

Setup:

• 1 Owner (founder)
• 1-2 Admins (co-founders, leads)
• 1-2 Members (team)

Rationale: Everyone can work, admins handle team management.

2. Agency (10-25 people)

Setup:

• 1 Owner (agency owner)
• 2-3 Admins (department heads)
• 15-20 Members (account managers, creators)
• 2-5 Viewers (clients)

Rationale: Hierarchy with client visibility.

3. Enterprise (50+ people)

Setup:

• 1 Owner (IT administrator)
• 5-10 Admins (team leads)
• 40+ Members (employees)
• 10+ Viewers (stakeholders)

Rationale: Scaled management with many contributors.

4. Freelancer + Client

Setup:

• 1 Owner (freelancer)
• 1-2 Viewers (client stakeholders)

Rationale: Client can monitor without editing.

Best Practices

1. Principle of Least Privilege

Give minimum permissions needed:

✅ Good:

• Client monitoring campaign → Viewer
• Marketing creating links → Member
• Team lead managing settings → Admin

❌ Bad:

• Everyone is Admin
• Client has Member access

2. Regular Audits

Review permissions quarterly:

# Get all members
curl https://api.linkforty.com/api/organizations/org_abc123/members \
  -H "Authorization: Bearer $API_KEY" \
  | jq '.[] | {name: .name, role: .role, joined: .joined_at}'

Remove inactive members, adjust roles.

3. Document Role Assignments

Keep a record of why roles were assigned:

# Team Roles

- john@example.com (Owner) - Founder, handles billing
- sarah@example.com (Admin) - Marketing lead
- mike@example.com (Member) - Content creator
- client@nike.com (Viewer) - Client stakeholder

4. Limit Admins

Don't make everyone admin:

Recommended:

• Owners: 1
• Admins: 10-20% of team
• Members: 70-80% of team
• Viewers: Case-by-case

Troubleshooting

"You don't have permission"

Cause: Your role doesn't allow this action

Fix:

1. Check your role (profile menu)
2. Contact admin/owner to elevate permissions
3. Ask admin to perform action

Can't Change Own Role

Cause: Can't demote yourself

Fix: Ask another admin/owner to change your role

Can't Remove Owner

Cause: Owner can't be removed

Fix: Owner must transfer ownership first, then leave

Security

Access Control

• ✅ Role verification on every API call
• ✅ UI enforcement hides unauthorized actions
• ✅ Audit logging tracks role changes (Enterprise)

Recommendations

• ✅ Regularly review team members
• ✅ Remove inactive accounts
• ✅ Use Viewer role for read-only access
• ✅ Require 2FA for Admins and Owners (Enterprise)

Related Guides

• Organizations - Organization management
• Inviting Members - Add team members
• Projects - Organize with projects

Next Steps

1. Review current team roles
2. Assign appropriate permissions
3. Document role decisions
4. Set up regular permission audits