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

# Roles & Permissions

> 5-tier role-based access control (RBAC) for workspaces, agent roles, and the Crewship equality philosophy.

# Roles & Permissions

Crewship implements role-based access control at two levels: **workspace roles** (human users) and **agent roles** (AI agents within crews).

## Workspace Roles (Human Users)

Users are assigned one of five roles within a workspace:

| Role        | Level    | Permissions                                    |
| ----------- | -------- | ---------------------------------------------- |
| **OWNER**   | Highest  | Full control, billing, delete workspace        |
| **ADMIN**   | High     | Manage users, crews, credentials, integrations |
| **MANAGER** | Medium   | Create and manage crews, view credentials      |
| **MEMBER**  | Standard | Read access to all workspace data              |
| **VIEWER**  | Lowest   | Read access to all workspace data              |

Roles are defined as the `OrgRole` enum in the Prisma schema:

```prisma theme={null}
enum OrgRole {
  OWNER
  ADMIN
  MANAGER
  MEMBER
  VIEWER
}
```

### Permission Mapping (Code Implementation)

The `canRole()` function in Go maps roles to three internal actions:

| Action   | Allowed Roles             | Used For                                          |
| -------- | ------------------------- | ------------------------------------------------- |
| `read`   | All authenticated members | View crews, agents, missions, logs                |
| `create` | OWNER, ADMIN, MANAGER     | Create crews, agents, credentials, missions       |
| `manage` | OWNER, ADMIN              | Delete resources, manage members, update settings |

<Note>
  In the current implementation, MEMBER and VIEWER have identical permissions (both map to `read` only). The distinction exists in the schema for future granularity (e.g., MEMBER may gain `send_message` or `run_agent` permissions).
</Note>

### Signup Control

New user registration is controlled by the `CREWSHIP_ALLOW_SIGNUP` environment variable (or `auth.allow_signup` in YAML config). When disabled, only existing users can invite new members.

## Agent Roles

Every AI agent has one of two functional roles:

<CardGroup cols={2}>
  <Card title="AGENT" icon="robot">
    Individual contributor. Executes tasks, writes code, runs tools. The standard role for most agents.
  </Card>

  <Card title="LEAD" icon="crown">
    Crew orchestrator. Assigns tasks to agents, creates missions, monitors progress. Has access to the full sidecar API.
  </Card>
</CardGroup>

### Agent Role Capabilities

| Capability       | AGENT     | LEAD      |
| ---------------- | --------- | --------- |
| Execute tasks    | Yes       | Yes       |
| Use memory       | Yes       | Yes       |
| Peer queries     | Yes       | Yes       |
| Assign tasks     | No        | Yes       |
| Create missions  | No        | Yes       |
| See crew members | Via peers | Full list |

### The Equality Principle

<Note>
  Agent roles are **functional, not hierarchical**. A Lead is an equal colleague with orchestration responsibility -- not a boss. This is a core Crewship philosophy.
</Note>

The system prompt for each role reflects this equality:

**AGENT:**

> You are part of a crew on the Crewship -- an expedition with a shared purpose that transcends any individual.

**LEAD:**

> You are a crew member with orchestration responsibility. You are not a boss -- you are an equal colleague who carries the soul and mission of the expedition to the whole team.

## Internal API Authentication

The internal API (sidecar-to-crewshipd communication) uses token-based authentication:

```
X-Internal-Token: {auto-generated-64-char-hex-token}
```

This token is:

1. Auto-generated cryptographically at startup if not configured
2. Passed to sidecar processes via the IPC config
3. Verified on every internal API request

<Warning>
  Never hardcode the internal token. The auto-generation ensures each deployment gets a unique token. If you need to set it explicitly (e.g., for multi-server setups), use `CREWSHIP_INTERNAL_TOKEN`.
</Warning>

## Container Security Boundaries

Agent processes run as UID 1001, while the sidecar runs as UID 1002. This prevents agents from:

* Reading the sidecar's credential store
* Modifying network policy configuration
* Accessing the IPC token
* Tampering with the proxy's authentication headers

See [Container Isolation](/security/container-isolation) for details.

## Credential Access Control

Credentials are protected by multiple layers:

1. **Workspace scoping:** Credentials belong to a workspace
2. **Agent assignment:** Credentials must be explicitly assigned to agents
3. **Encryption at rest:** AES-256-GCM with versioned keys
4. **Sidecar injection:** Agents never see raw credential values
5. **Keeper gating:** L2+ credentials require AI evaluation
6. **Audit trail:** All credential access is logged

## JWT Authentication

User authentication uses JWT tokens signed with `NEXTAUTH_SECRET`:

* WebSocket connections use short-lived tokens (`ws_token_expiry`, default 5 minutes)
* API requests use session-based JWT tokens
* Token validation is handled by the middleware layer