---
title: "Organization administration"
description: "Administer StackShip identity, projects, workspaces, and access."
---

> 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.

# Organization administration

An organization is StackShip's tenant and identity boundary. Every project,
workspace, run, state version, credential profile, policy set, and audit event
belongs to exactly one organization. The API derives that organization from
the authenticated session's active membership; a caller-supplied organization
id is never accepted as authorization.

StackShip has no billing, plan, seat, invoice, or payment-management surface today.

## Identity

Better Auth owns sign-in, sessions, organizations, and memberships. Production
identity supports:

- email and password;
- Google login;
- the Better Auth organization plugin;
- enterprise OIDC and SAML SSO;
- SCIM 2.0 provisioning; and
- the OAuth 2.1 Provider plugin used by the MCP resource.

Authentication is served from `https://api.stackship.run/api/auth`. A protected
product request fails closed when its session, active organization, or live
membership cannot be verified.

## Product hierarchy

| Object | Responsibility |
| --- | --- |
| Organization | Tenant, identity, membership, policy, credentials, and audit boundary |
| Project | Named grouping for related workspaces |
| Workspace | One OpenTofu configuration, run history, and state lineage |
| Run | One immutable-input plan, policy, approval, and optional apply attempt |

Projects are organizational groupings, not a separate tenant. Moving between
projects never relaxes the organization constraint on a query.

## Roles

The first release maps Better Auth organization roles to a fixed permission
set:

| Role | Access |
| --- | --- |
| `owner` | All launch permissions |
| `admin` | All launch permissions |
| `member` | Read projects, workspaces, runs, state, ordinary artifacts, credential metadata, policies, and VCS metadata; create runs |

An unknown, missing, or stale role grants nothing. Custom roles, teams, and
project-specific grants are not part of the current product surface.
Owners and administrators can invite members and manage non-owner roles from
the organization dashboard. Removing a member requires an explicit second
confirmation; owner and current-account removal controls are never rendered.

See [roles and permissions](/admin/teams) for the exact permission list.

## Administrative surfaces

- **Projects** — create and inspect project groupings.
- **Workspaces** — create workspaces and change the execution region or exact
  supported OpenTofu version. US is currently launch-enabled; EU remains
  disabled until EU execution capacity is available.
- **GitHub App** — install the single supported VCS integration and select
  repositories. Read-only members never receive an installation control.
- **Credentials** — configure versioned cloud federation profiles. Generic
  secret support is documented on the variables page when enabled.
- **Policies** — publish immutable Rego versions and attach one to a workspace.
- **Audit** — read the newest organization-scoped product events.

Organization SSO and SCIM configuration are production identity capabilities
with their own operator-sensitive setup:

- [Enterprise SSO](/admin/sso)
- [SCIM provisioning](/admin/scim)

## Fail-closed boundaries

- Dashboard routes require a live Better Auth session and active membership.
- Native `/v1` operations derive the tenant from that session.
- OpenTofu native cloud requests accept only service-account bearer
  credentials with a live organization and workspace boundary.
- MCP access tokens must have the MCP resource as their audience and include
  `mcp:tools`.
- Internal runner, broker, Workflow, and GitHub webhook credentials are never
  accepted as user authentication.

## Related pages

- [Authentication](/authentication)
- [Roles and permissions](/admin/teams)
- [Access tokens](/admin/tokens)
- [Architecture](/architecture)

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