---
title: "Roles and permissions"
description: "The fixed organization roles and their fail-closed permission mapping."
---

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

# Roles and permissions

StackShip authorizes every product operation with both a live organization
membership and a named permission. The first release has three organization
roles and no custom-role editor.

## Role mapping

`owner` and `admin` receive the full launch permission set. `member` receives:

- `project:read`
- `workspace:read`
- `state:outputs:read`
- `run:create`
- `run:read`
- `artifact:read`
- `credential:read_metadata`
- `policy:read`
- `vcs:read`

The full administrative set is:

| Area | Permissions |
| --- | --- |
| Projects | `project:create`, `project:read`, `project:admin` |
| Workspaces | `workspace:create`, `workspace:read`, `workspace:admin` |
| State | `state:outputs:read`, `state:read`, `state:write`, `state:lock`, `state:recover` |
| Runs | `run:create`, `run:read`, `run:cancel`, `run:approve`, `run:recover` |
| Artifacts | `artifact:read`, `artifact:read_sensitive` |
| Credentials | `credential:read_metadata`, `credential:write` |
| Policy | `policy:read`, `policy:write`, `policy:override_soft` |
| GitHub | `vcs:install`, `vcs:read`, `vcs:admin` |

Unknown Better Auth roles map to an empty set. Multiple role values are parsed
as a set; the presence of `owner` or `admin` selects the administrative
mapping.

## Enforcement

The permission check is not a dashboard-only visibility rule. The API repeats
the organization constraint in database queries and rejects an operation
before accessing a target outside the active organization.

Some reads have additional conditions:

- raw plan and emergency-state artifacts require
  `artifact:read_sensitive`, a typed operator reason, and recent
  step-up authentication;
- emergency state additionally requires `state:recover`; `run:recover`
  alone never authorizes access to state bytes;
- raw state download requires both `state:read` and
  `artifact:read_sensitive`; ordinary members receive neither permission;
- restricted download routes reject every non-empty query string, including
  a reason placed in the URL, before reading state or artifact storage;
- every accepted raw-state download records its reason in an audit event
  before the response stream is released;
- a soft policy override requires `policy:override_soft`; and
- approve, reject, and cancel controls are returned only when the exact action
  is currently available.

## Current scope

The permission map is intentionally fixed. A custom role model,
team hierarchy, project-specific grants, and delegated role administration are
not available today. The Better Auth organization membership remains
the authority.

## Related pages

- [Organization administration](/admin)
- [Authentication](/authentication)
- [Run approvals](/runs/approvals)
- [v1 REST API](/automation/api)

Source: https://docs.stackship.run/admin/teams/index.mdx