> ## Documentation Index
> Fetch the complete documentation index at: https://team.k0labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RBAC & Permissions

> Role-based access control and permissions for k0rdent

## k0rdent Platform — RBAC & Permissions

## Atlas Roles (Provider Console — Platform-Scoped)

Atlas operates in a single platform organization context. No customer org isolation needed.

| Role                | Description                   | Capabilities                                                             |
| ------------------- | ----------------------------- | ------------------------------------------------------------------------ |
| `super_admin`       | Full platform control         | All operations, system config                                            |
| `provider_admin`    | Organization management       | Create/manage customer orgs, impersonate users, modify settings          |
| `provider_operator` | Infrastructure operations     | Provision servers, manage resource                                       |
| `provider_revenue`  | Business & revenue operations | View all data, analytics, billing, pricing, audit logs (read-only infra) |
| `support`           | Customer support              | Read-only access                                                         |

### Atlas Permission Matrix

| Permission         | super\_admin | provider\_admin | provider\_operator | provider\_revenue | support |
| ------------------ | :----------: | :-------------: | :----------------: | :---------------: | :-----: |
| `system:*`         |       ✅      |        ❌        |          ❌         |         ❌         |    ❌    |
| `tenants:*`        |       ✅      |        ✅        |          ❌         |         ❌         |    ❌    |
| `servers:*`        |       ✅      |        ✅        |          ✅         |         ❌         |    ❌    |
| `servers:read`     |       ✅      |        ✅        |          ✅         |         ✅         |    ✅    |
| `clusters:*`       |       ✅      |        ✅        |          ✅         |         ❌         |    ❌    |
| `clusters:read`    |       ✅      |        ✅        |          ✅         |         ✅         |    ✅    |
| `projects:*`       |       ✅      |        ✅        |          ❌         |         ❌         |    ❌    |
| `projects:read`    |       ✅      |        ✅        |          ✅         |         ✅         |    ✅    |
| `analytics:read`   |       ✅      |        ✅        |          ❌         |         ✅         |    ❌    |
| `analytics:export` |       ✅      |        ✅        |          ❌         |         ✅         |    ❌    |
| `billing:*`        |       ✅      |        ✅        |          ❌         |         ✅         |    ❌    |
| `pricing:write`    |       ✅      |        ✅        |          ❌         |         ✅         |    ❌    |
| `audit:read`       |       ✅      |        ✅        |          ❌         |         ✅         |    ✅    |
| `users:read`       |       ✅      |        ✅        |          ✅         |         ✅         |    ✅    |

***

## Arc Roles (Customer Portal — Multi-Tenant)

Arc uses BetterAuth's organization plugin for multi-tenancy. Roles exist at two levels: organization and project.

### Organization Roles

| Role     | Scope             | Description                                                       |
| -------- | ----------------- | ----------------------------------------------------------------- |
| `owner`  | All projects      | Full org control, destructive actions, ownership transfer         |
| `admin`  | All projects      | Org settings, billing, member management, all project access      |
| `member` | Assigned projects | Access `visibility: 'org'` projects as implicit viewer, own usage |

### Owner vs Admin Boundary

Admins can build up, only owners can tear down. This prevents a rogue admin from nuking the org or locking out the account holder.

| Action                            | Owner | Admin | Member |
| --------------------------------- | :---: | :---: | :----: |
| Delete organization               |   ✅   |   ❌   |    ❌   |
| Transfer ownership                |   ✅   |   ❌   |    ❌   |
| Downgrade/cancel billing plan     |   ✅   |   ❌   |    ❌   |
| Remove other admins               |   ✅   |   ❌   |    ❌   |
| Invite/promote to admin           |   ✅   |   ✅   |    ❌   |
| Manage billing methods & invoices |   ✅   |   ✅   |    ❌   |
| View org-wide usage               |   ✅   |   ✅   |    ❌   |
| View own project usage            |   ✅   |   ✅   |    ✅   |
| All other org settings            |   ✅   |   ✅   |    ❌   |
| Create projects                   |   ✅   |   ✅   |    ❌   |
| Access all projects               |   ✅   |   ✅   |    ❌   |
| Access assigned projects          |   ✅   |   ✅   |    ✅   |

### Project Roles

| Role     | Capabilities                                                    |
| -------- | --------------------------------------------------------------- |
| `admin`  | Full project control, manage project members, change visibility |
| `member` | Deploy, manage resources within project                         |
| `viewer` | Read-only access to project resources                           |

### Project Visibility

| Value             | Behavior                                                   |
| ----------------- | ---------------------------------------------------------- |
| `'org'` (default) | All org members have implicit viewer access                |
| `'members_only'`  | Only explicit project members + org owner/admin can access |

### Access Control Matrix

| Org Role | Project Visibility | Project Role | Access Level      |
| -------- | ------------------ | ------------ | ----------------- |
| `owner`  | any                | any          | ✅ Full access     |
| `admin`  | any                | any          | ✅ Full access     |
| `member` | `org`              | none         | ✅ Implicit viewer |
| `member` | `members_only`     | none         | ❌ No access       |
| `member` | `members_only`     | `viewer`     | ✅ Read-only       |
| `member` | `members_only`     | `member`     | ✅ Member          |
| `member` | `members_only`     | `admin`      | ✅ Project admin   |

***

## Permissions Schema

### Arc Organization Permissions

```typescript theme={null}
const arcOrgRolePermissions = {
  owner: [
    'org:*',              // All org operations
    'org:delete',         // Delete organization
    'org:transfer',       // Transfer ownership
    'org:billing',        // Manage billing methods, invoices, plan
    'org:billing:usage:all', // View org-wide usage
    'org:members:admin',  // Invite/remove admins
    'projects:*',         // All project operations
    'clusters:*',         // All cluster operations
  ],
  admin: [
    'org:admin',          // Org settings
    'org:write',          // Modify org properties
    'org:billing',        // Manage billing methods, invoices
    'org:billing:usage:all', // View org-wide usage
    'org:members:admin',  // Invite/promote members
    'projects:*',         // All project operations
    'clusters:*',         // All cluster operations
  ],
  member: [
    'org:read',           // View org info
    'org:billing:usage:own', // View own project usage
    'projects:read',      // View org-visible projects
    'clusters:read',      // View clusters in accessible projects
  ],
};
```

### Arc Project Permissions

```typescript theme={null}
const arcProjectRolePermissions = {
  admin: [
    'projects:admin',     // Full project control
    'projects:members',   // Manage project members
    'projects:settings',  // Change visibility, settings
    'clusters:*',         // All cluster operations in project
  ],
  member: [
    'clusters:read',      // View clusters
    'clusters:write',     // Deploy, manage resources
    'clusters:kubeconfig', // Access kubeconfig
  ],
  viewer: [
    'projects:read',      // View project info
    'clusters:read',      // View clusters (read-only)
  ],
};
```

### Billing Permission Breakdown

| Permission              | Description                                    | Owner | Admin | Member |
| ----------------------- | ---------------------------------------------- | :---: | :---: | :----: |
| `org:billing`           | Manage payment methods, invoices, plan changes |   ✅   |   ✅   |    ❌   |
| `org:billing:usage:all` | View usage across all projects in org          |   ✅   |   ✅   |    ❌   |
| `org:billing:usage:own` | View usage for projects user belongs to        |   ✅   |   ✅   |    ✅   |

***

## First User & Default Behavior

| Event                     | Result                                                              |
| ------------------------- | ------------------------------------------------------------------- |
| User creates organization | User gets `owner` role                                              |
| Org creation              | Auto-creates a "default" project                                    |
| Owner on default project  | Auto-assigned as project `admin`                                    |
| New project created       | `visibility: 'org'` by default (can set `members_only` on creation) |
| Project creator           | Auto-assigned as project `admin`                                    |

***

## Schema Representation

```typescript theme={null}
// Organization membership (BetterAuth organization plugin)
organization_members {
  user_id       // FK → auth.users
  organization_id // FK → auth.organizations
  role          // 'owner' | 'admin' | 'member'
}

// Projects
projects {
  id
  organization_id // FK → auth.organizations
  name
  slug
  visibility    // 'org' | 'members_only' — default 'org'
  created_by    // FK → auth.users
  ...
}

// Project membership
project_members {
  user_id       // FK → auth.users
  project_id    // FK → projects
  role          // 'admin' | 'member' | 'viewer'
}
```

***

## Permission Checking Logic

```typescript theme={null}
// Resolve effective access for a user on a project
function getProjectAccess(
  orgRole: 'owner' | 'admin' | 'member',
  projectVisibility: 'org' | 'members_only',
  projectRole?: 'admin' | 'member' | 'viewer' | null,
): 'admin' | 'member' | 'viewer' | 'none' {
  // Owner/admin get full access to everything
  if (orgRole === 'owner' || orgRole === 'admin') return 'admin';

  // Explicit project role always takes precedence
  if (projectRole) return projectRole;

  // Org members get implicit viewer on org-visible projects
  if (orgRole === 'member' && projectVisibility === 'org') return 'viewer';

  return 'none';
}
```