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

# Roles & Permissions

> Understand the role hierarchy, what each role can access, and how permissions are enforced

Zygo uses a hierarchical role system to control access within each tenant. Roles are assigned per-tenant — a user can be an **Admin** in one tenant and a **Viewer** in another.

## Role Hierarchy

Roles are ordered by privilege level. Higher roles inherit all permissions from lower ones.

```
Admin → Editor → Viewer → User
```

> [tab] User
>
> The most restricted role. Designed for external users who only interact with web forms.
>
> **Can:**
>
> * View and submit published web forms
>
> **Cannot:**
>
> * View flows, runs, credentials, data tables, tickets, dashboards, or logs

> [tab] Viewer
>
> Read-only access across the tenant.
>
> **Can:**
>
> * View flows, runs, and run logs
> * View credentials (data is masked)
> * View data tables and records
> * View tickets and comments
> * View dashboards
> * View tenant logs
> * View tenant member list and roles
>
> **Cannot:**
>
> * Create, edit, or delete any resources
> * Run flows
> * Manage members or tenant settings

> [tab] Editor
>
> Full read and write access to resources.
>
> **Can do everything a Viewer can, plus:**
>
> * Create, edit, and delete flows
> * Run flows and cancel jobs
> * Create, edit, and delete credentials (own or admin-owned)
> * Create, edit, and delete data table records and schemas
> * Create, edit, and delete tickets and comments
> * Create, edit, and delete dashboards
> * Toggle flow publish state
> * Save and edit form definitions
>
> **Cannot:**
>
> * Manage tenant members or roles
> * Configure tenant settings
> * Modify platform-level fields

> [tab] Admin
>
> Full control over the tenant.
>
> **Can do everything an Editor can, plus:**
>
> * Add and remove tenant members
> * Assign and change member roles
> * Update tenant settings (contact email, approved domains, magic link login)
> * Delete the tenant
> * Modify any credential (regardless of ownership)

## Superadmin

Superadmin is a **platform-level** privilege, not a tenant role. Superadmins bypass all role and tenant checks.

> [accordion] What can a Superadmin do?
>
> * Access any tenant without being a member
> * Create and manage user accounts
> * Grant or revoke superadmin status
> * Set platform-level tenant fields (license, flow cap)
> * View system-wide logs
> * Access all API endpoints without restriction

> [accordion] How is Superadmin assigned?
>
> Superadmin status is set on the user account by an existing superadmin via the `super` field when updating a user. It cannot be self-assigned.

## Permission Matrix

A complete breakdown of which roles can access each resource type:

| Resource | User | Viewer | Editor | Admin |
| - | :-: | :-: | :-: | :-: |
| Web forms (view & submit) | ✓ | ✓ | ✓ | ✓ |
| Flows (list, view) | | ✓ | ✓ | ✓ |
| Flows (create, edit, delete) | | | ✓ | ✓ |
| Flows (run, publish) | | | ✓ | ✓ |
| Runs & Jobs (view) | | ✓ | ✓ | ✓ |
| Jobs (cancel) | | | ✓ | ✓ |
| Credentials (list, view masked) | | ✓ | ✓ | ✓ |
| Credentials (create, edit, delete) | | | ✓ | ✓ |
| Data tables (list, view) | | ✓ | ✓ | ✓ |
| Data tables (create, edit, delete) | | | ✓ | ✓ |
| Tickets (list, view) | | ✓ | ✓ | ✓ |
| Tickets (create, edit, delete) | | | ✓ | ✓ |
| Comments (view) | | ✓ | ✓ | ✓ |
| Comments (create, delete) | | | ✓ | ✓ |
| Dashboards (list, view) | | ✓ | ✓ | ✓ |
| Dashboards (create, edit, delete) | | | ✓ | ✓ |
| Tenant logs | | ✓ | ✓ | ✓ |
| Member list & roles | | ✓ | ✓ | ✓ |
| Add/remove members | | | | ✓ |
| Assign roles | | | | ✓ |
| Tenant settings | | | | ✓ |
| Delete tenant | | | | ✓ |

## How Roles Are Enforced

**1. Authentication**

Every request is authenticated via a browser session cookie or an API token in the `token` header. This identifies **who** is making the request.

**2. Tenant Resolution**

The tenant is determined from the URL path (`/tenants/{tenant_id}/...`). For browser users, this is validated against the active session. For API token users, membership is verified via a database lookup.

**3. Role Check**

The user's roles in the resolved tenant are compared against the minimum role required by the endpoint. If the user's highest role doesn't meet the minimum, the request is rejected with a `403`.

**4. Resource Scoping**

The requested resource (flow, ticket, etc.) is fetched with a tenant filter, ensuring users can only access resources within their authorized tenant — even if they guess a resource ID from another tenant.

> [!NOTE]
>
> Roles are checked **before** any database query for the resource. If a user lacks permission, the request is rejected without revealing whether the resource exists.

## Credential Ownership

Credentials have an additional ownership layer on top of roles. When a user creates a credential, they become its **owner**.

* **Owners** can always edit or delete their own credentials, regardless of role
* **Admins** can edit or delete any credential in the tenant
* **Editors** can create credentials but can only modify credentials they own
* **Viewers** can see credential names and labels but all sensitive data is masked


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.