# Team and Roles

> Manage workspace team members with role-based access control including Owner, Admin, and User roles.

Source: https://0.0.0.0:8080/docs/team-and-roles

PromptRails provides role-based access control (RBAC) for workspace team management. Each workspace member is assigned a role that determines their permissions.

## Role Hierarchy

PromptRails defines three workspace roles with a clear hierarchy:

```
Owner > Admin > User
```

### Owner

The workspace owner has full control over all resources and settings. There is exactly one owner per workspace (the user who created it).

| Permission                                   | Allowed |
| -------------------------------------------- | ------- |
| Manage all resources (agents, prompts, etc.) | Yes     |
| Manage credentials                           | Yes     |
| Manage API keys                              | Yes     |
| Manage team members                          | Yes     |
| Change member roles                          | Yes     |
| Transfer ownership                           | Yes     |
| Delete the workspace                         | Yes     |
| Manage billing and plans                     | Yes     |

### Admin

Admins have broad permissions but cannot perform destructive workspace-level operations.

| Permission                                   | Allowed |
| -------------------------------------------- | ------- |
| Manage all resources (agents, prompts, etc.) | Yes     |
| Manage credentials                           | Yes     |
| Manage API keys                              | Yes     |
| Manage team members                          | Yes     |
| Change member roles (below their level)      | Yes     |
| Transfer ownership                           | No      |
| Delete the workspace                         | No      |
| Manage billing and plans                     | Yes     |

### User

Users can work with resources but have limited administrative access.

| Permission                            | Allowed |
| ------------------------------------- | ------- |
| View and execute agents               | Yes     |
| View and execute prompts              | Yes     |
| View executions and traces            | Yes     |
| Create and manage their own resources | Yes     |
| Manage credentials                    | No      |
| Manage API keys                       | No      |
| Manage team members                   | No      |
| Manage billing                        | No      |

## Adding Members

Invite new members from the workspace settings in the PromptRails dashboard. Owners and admins can enter the user's email address and assign a role during the invitation flow.

The invited user receives an email with an invitation link. Once accepted, they are added to the workspace with the specified role.

## Invitation Flow

1. **Owner/Admin sends invitation** -- Specifies email and role
2. **Invitation email sent** -- Contains a unique invitation link
3. **User accepts** -- Clicks the link and creates an account (if new) or logs in
4. **Member added** -- User is added to the workspace with the assigned role

### Invitation Statuses

| Status     | Description                                |
| ---------- | ------------------------------------------ |
| `pending`  | Invitation sent, awaiting acceptance       |
| `accepted` | User accepted the invitation               |
| `revoked`  | Invitation was cancelled before acceptance |

## Removing Members

Remove members from the workspace settings screen in the dashboard.

Removing a member revokes their access immediately. Their previously created resources remain in the workspace.

## Changing Roles

Change member roles from the same team management screen in the dashboard.

Role changes take effect immediately for all subsequent requests.

## API Key Auth vs User Auth

PromptRails supports two authentication methods:

### User Authentication (JWT)

- Used by the dashboard (frontend)
- Authenticated via email/password login
- Permissions based on workspace role
- Session-based with access + refresh tokens

### API Key Authentication

- Used by SDKs, CLI, and integrations
- Authenticated via `X-API-Key` header
- Permissions based on API key scopes (not user roles)
- Workspace-scoped (each key belongs to one workspace)

API keys provide more granular control than roles. A user with the "owner" role might create an API key with only `agents:read` scope for a specific integration.

## System Roles

In addition to workspace roles, PromptRails has system-level roles:

| Role    | Description                                   |
| ------- | --------------------------------------------- |
| `admin` | Platform administrator (access to backoffice) |
| `user`  | Regular platform user                         |

System roles are separate from workspace roles. A user can be a system `user` but a workspace `owner`.

## Plan Limits

Team member counts are subject to plan limits:

| Plan       | Max Team Members |
| ---------- | ---------------- |
| Free       | 1                |
| Starter    | 3                |
| Pro        | 10               |
| Enterprise | Unlimited        |

Attempting to add members beyond the plan limit returns a `402 Payment Required` error.

## Related Topics

- [Workspace Management](/docs/workspace-management) -- Workspace creation and settings
- [API Keys and Scopes](/docs/api-keys-and-scopes) -- API key permissions
- [Security](/docs/security) -- Authentication and authorization
- [Billing and Plans](/docs/billing-and-plans) -- Team member limits