Organizations

Organizations allow teams to collaborate on link management, with separate workspaces, billing, and member access control.

Overview

An organization is a workspace where teams can:

• Create and manage links together
• Share analytics and insights
• Control access with roles and permissions
• Manage billing and subscriptions centrally
• Organize work with projects

Key Concepts:

• Personal Workspace - Your individual account (always exists)
• Organization - Team workspace with multiple members
• Owner - Creates and owns the organization (billing, deletion)
• Members - Team members with assigned roles

Creating an Organization

Via Dashboard

1. Click your profile menu (top right)
2. Select "Create Organization"
3. Enter organization name
4. Click "Create"

You're now the organization owner and can invite team members.

Via API

curl -X POST https://api.linkforty.com/api/organizations \
  -H "Authorization: Bearer $LINKFORTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Marketing Team"
  }'

Response:

{
  "id": "org_abc123",
  "name": "Acme Marketing Team",
  "slug": "acme-marketing-team-x7y9z2",
  "owner_id": "user_456",
  "subscription_tier": "free",
  "created_at": "2024-03-15T10:30:00Z"
}

Note: The slug is auto-generated and includes a random string for uniqueness.

Personal Workspace vs Organization

Feature	Personal Workspace	Organization
Members	Just you	Multiple team members
Billing	Personal payment	Shared team billing
Roles	You're the owner	Owner, Admin, Member, Viewer
Permissions	Full access	Role-based access control
Invitations	Not applicable	Email invitations
Projects	Personal projects	Team projects
Switching	N/A	Switch between orgs

Organization Structure

Organization: Acme Marketing Team
├── Owner: john@acme.com
├── Members:
│   ├── Admin: sarah@acme.com
│   ├── Member: mike@acme.com
│   └── Viewer: emma@acme.com
├── Links: 1,248 links
├── Projects:
│   ├── Instagram Campaigns
│   ├── Email Marketing
│   └── Product Launches
└── Billing: Pro Plan ($29/month)

Managing Your Organizations

Viewing All Organizations

Dashboard:

• Click profile menu → "Switch Organization"
• See all organizations you're a member of

API:

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

Response:

[
  {
    "id": "org_personal",
    "name": "Personal Workspace",
    "role": "owner",
    "member_count": 1,
    "joined_at": "2024-01-15T10:00:00Z"
  },
  {
    "id": "org_abc123",
    "name": "Acme Marketing Team",
    "role": "admin",
    "member_count": 12,
    "joined_at": "2024-02-20T14:30:00Z"
  },
  {
    "id": "org_def456",
    "name": "Client: Nike",
    "role": "member",
    "member_count": 5,
    "joined_at": "2024-03-10T09:15:00Z"
  }
]

Switching Between Organizations

All your work in LinkForty is scoped to the active organization. When you switch organizations, you see that org's:

• Links
• Analytics
• Projects
• Team members
• Settings

Via Dashboard:

1. Click profile menu
2. Select "Switch Organization"
3. Choose organization from list
4. Dashboard updates to show org's data

Via API:

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

Response:

{
  "token": "new_jwt_token_with_org_context",
  "user": {
    "id": "user_456",
    "email": "john@example.com",
    "name": "John Doe"
  },
  "organization": {
    "id": "org_abc123",
    "name": "Acme Marketing Team",
    "role": "admin"
  }
}

Important: Save the new token - it includes your organization context.

Organization Details

Get detailed information:

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

Response:

{
  "id": "org_abc123",
  "name": "Acme Marketing Team",
  "slug": "acme-marketing-team-x7y9z2",
  "owner_id": "user_456",
  "subscription_tier": "pro",
  "subscription_status": "active",
  "member_count": 12,
  "link_count": 1248,
  "project_count": 8,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-03-10T14:22:00Z"
}

Usage and Limits

Each organization has limits based on its subscription tier.

Checking Usage

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

Response:

{
  "usage": {
    "links": 1248,
    "members": 12,
    "domains": 2
  },
  "limits": {
    "links": 10000,
    "members": 25,
    "domains": 5
  },
  "tier": "pro"
}

Subscription Tiers

Tier	Links	Members	Custom Domains	Price
Free	1,000	1	0	$0
Pro	10,000	25	5	$29/month
Enterprise	Unlimited	Unlimited	Unlimited	Custom

Updating Organization

Rename Organization

Dashboard:

1. Go to Settings → Organization
2. Update name
3. Click "Save"

API:

curl -X PUT https://api.linkforty.com/api/organizations/org_abc123 \
  -H "Authorization: Bearer $LINKFORTY_API_KEY" \
  -H "Content-Type": application/json" \
  -d '{
    "name": "Acme Marketing & Growth Team"
  }'

Requires: Admin or Owner role

Update Settings

curl -X PUT https://api.linkforty.com/api/organizations/org_abc123 \
  -H "Authorization: Bearer $LINKFORTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "defaultAttributionWindow": 168,
      "requireApprovalForLinks": false,
      "allowMembersToInvite": true
    }
  }'

Deleting an Organization

⚠️ Warning: This permanently deletes:

• All links
• All analytics data
• All projects
• All team members
• All custom domains
• Subscription and billing

Only the organization owner can delete.

Via Dashboard

1. Go to Settings → Organization
2. Scroll to "Danger Zone"
3. Click "Delete Organization"
4. Type organization name to confirm
5. Click "Delete Permanently"

Via API

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

Response:

{
  "message": "Organization deleted successfully"
}

Requires: Owner role

Common Workflows

1. Agency Managing Multiple Clients

Create separate organizations for each client:

# Client 1: Nike
curl -X POST https://api.linkforty.com/api/organizations \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"name": "Client: Nike"}'

# Client 2: Adidas
curl -X POST https://api.linkforty.com/api/organizations \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"name": "Client: Adidas"}'

Benefits:

• ✅ Separate billing per client
• ✅ Isolated data and analytics
• ✅ Client-specific team members
• ✅ Easy context switching

2. Company with Multiple Teams

One organization, multiple projects:

Organization: Acme Corp
├── Project: Marketing Team
├── Project: Product Team
└── Project: Sales Team

Benefits:

• ✅ Shared billing
• ✅ Cross-team visibility
• ✅ Centralized management

3. Freelancer with Personal + Client Work

Use personal workspace + client organizations:

Personal Workspace (Your projects)
+ Client Organization 1
+ Client Organization 2

Benefits:

• ✅ Keep personal work separate
• ✅ Professional client workspaces
• ✅ Easy switching

Best Practices

1. Clear Naming Convention

✅ Good:

• "Acme Marketing Team"
• "Client: Nike - Spring Campaign"
• "Personal - Side Projects"

❌ Bad:

• "Org1"
• "Test"
• "New Organization"

2. Regular Usage Monitoring

async function checkUsageLimits(orgId: string) {
  const usage = await fetch(`/api/organizations/${orgId}/usage`);
  const data = await usage.json();

  if (data.usage.links / data.limits.links > 0.8) {
    console.warn('⚠️ 80% of link limit reached');
    notifyAdmin('Consider upgrading plan');
  }
}

3. Organize with Projects

Don't create separate organizations for different campaigns - use projects instead:

✅ Good:

Organization: Acme Marketing
├── Project: Spring Sale 2024
├── Project: Product Launch
└── Project: Email Campaigns

❌ Bad:

Organization: Spring Sale
Organization: Product Launch
Organization: Email Campaigns

4. Document Organization Purpose

Add description in settings:

{
  "name": "Acme Marketing Team",
  "settings": {
    "description": "Main marketing team workspace for all campaigns",
    "purpose": "production",
    "owner": "marketing-team@acme.com"
  }
}

Troubleshooting

Can't See Organization's Links

Possible causes:

• Not switched to correct organization
• Removed from organization
• Organization deleted

Fix:

1. Check active organization (profile menu)
2. Switch to correct organization
3. Verify membership status

Can't Create Links (Limit Reached)

Cause: Organization hit plan limit

Fix:

1. Check usage: GET /api/organizations/:id/usage
2. Delete unused links
3. Upgrade plan

Can't Invite Members

Causes:

• Not an admin/owner
• Member limit reached

Fix:

1. Check your role
2. Check member usage vs limits
3. Upgrade plan if needed

Lost Access to Organization

Causes:

• Role changed to viewer (no access to some features)
• Removed from organization
• Organization deleted

Contact: Organization owner or admin

Security

Access Control

• ✅ Role-based permissions - See Roles & Permissions
• ✅ Audit logs - Track who did what (Enterprise)
• ✅ 2FA enforcement - Require for all members (Enterprise)
• ✅ IP whitelisting - Restrict access by IP (Enterprise)

Data Isolation

• ✅ Separate databases - Data scoped to organization
• ✅ No cross-org access - Can't see other org's data
• ✅ Secure deletion - Deleted orgs fully removed

API Reference

• Create Organization
• List Organizations
• Get Organization
• Update Organization
• Delete Organization
• Switch Organization

Related Guides

• Roles & Permissions - Understanding access control
• Inviting Members - Add team members
• Projects - Organize links within organizations
• Billing - Manage organization billing

Next Steps

1. Create your first organization
2. Invite team members
3. Set up projects for organization
4. Configure organization settings