Org Hierarchy

Rensei organizes all resources into a three-level hierarchy: Organization → Project → Environment. Understanding this model is the foundation for configuring access control, credential scoping, template subscriptions, and billing.

Organizations

An organization is the top-level billing and identity boundary. All members, API keys, M2M clients, SCIM directories, SSO connections, credentials, capacity pools, and BFSI compliance settings are scoped to an org.

Creating an organization

Organizations are provisioned by platform admins. When created, the platform automatically:

1. Generates a URL-safe slug derived from the organization name (e.g. acme-corp).
2. Provisions the plan-default SDLC template (sdlc-v2-authored) as an org-global workflow.
3. Installs the starter pack and sample workflow for onboarding.
4. Registers the org with WorkOS for SSO eligibility.

Key org fields

Feature flags

Org-level features gate platform capabilities. Admins configure them at Settings → Organization.

Projects

A project is the primary unit of work within an organization. Each project has:

• Its own tracker binding (Linear, Jira, Asana, GitHub Issues)
• Its own template subscriptions to SDLC workflows
• Its own environments for credential and configuration scoping
• Its own capacity pool assignments
• Membership governed by teams and RBAC

Creating a project

Project slug

The project slug is used everywhere the API and CLI accept a --project argument. It is derived from the project name on creation and is immutable after the first workflow is deployed. Use rensei project list to see slugs for all projects in your org.

rensei org activate acme-corp   # switch the CLI's active org context
rensei project list
# NAME          SLUG           TRACKER   CREATED
# Backend API   backend-api    linear    2026-05-01
# Web App       web-app        linear    2026-05-10

Environments

Every project supports multiple named environments that scope credential resolution and workflow configuration. The conventional set is dev, staging, and prod, but you can define any environment names your pipeline requires.

How environments work

When a workflow instance or agent session is dispatched, it carries an envName. The credential dispatch adapter resolves secrets using this three-step priority:

1. Project + environment-specific row in project_environments matching (projectId, envName)
2. Project-default credential for the kind (no env-name constraint)
3. Org-default credential for the kind

This means you can store a single LINEAR_API_KEY at the org level for development and override it with a scoped key for the prod environment of specific projects.

Workflow environments

Workflows use $ref expressions to read environment-aware configuration at runtime. See Workflow Environments for the full reference on $ref env-aware resolution.

Teams

Teams are named groups of organization members. They exist primarily to simplify project access grants - rather than adding individual members to each project, you add a team.

Team operations

Teams are managed via the org API (the rensei org CLI covers members, invites, and API keys, but not teams today):

# Create a team
curl -X POST https://rensei.ai/api/org/teams \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Platform Engineering" }'

# Add a member
curl -X POST https://rensei.ai/api/org/teams/{teamId}/members \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_...", "role": "member" }'

# Create a project under the team
curl -X POST https://rensei.ai/api/org/teams/{teamId}/projects \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "backend-api" }'

Teams are soft-deleted (the deletedAt timestamp is set) and their memberships are archived. There is no hard-delete of a team that still has active project associations - remove project associations first.

SCIM group → team mapping

When SCIM directory sync is enabled, groups from your identity provider map to Rensei teams automatically. See Directory Sync for the group-mapping configuration.

Admin operations

Org lookup by slug or ID

# Get org details including plan and feature flags
rensei org show --org acme-corp --json

The management API also exposes org lookup:

curl -H "Authorization: Bearer rsk_live_..." \
  https://rensei.ai/api/org/settings

Soft-delete behavior

Organizations and projects use soft deletes: a deletedAt timestamp is set, and all queries filter on isNull(deletedAt). Hard deletion is an operator-admin action covered in the operator docs.

Default SDLC must be org-global

The platform auto-provisions sdlc-v2-authored as an org-global workflow (project_id = NULL). If you archive this template or pin it to a specific project, new projects will not receive SDLC subscriptions and incoming trigger events will be silently dropped. See Template Subscriptions for the impact.

Access constraints (cascade-narrowing)

The org → project hierarchy is also the cascade-narrowing axis for model access. Each scope in the hierarchy can restrict the auth modes and models available to the scopes below it, but can never broaden what a parent has already restricted.

The rule

Effective access at a scope = parent's allowed set ∩ this scope's matrix

A child scope starts with all of the parent's grants and may only subtract. The default for an empty matrix at any scope is "inherit everything the parent allows."

graph TD
  SYS[System policy<br/>root - always allowed] -->|org may only narrow| ORG[Org access_policy<br/>JSONB, NOT NULL]
  ORG -->|project may only narrow| PRJ[Project access_policy<br/>JSONB, nullable = inherit]
  PRJ -->|effective modes| RES[Resolver picks one mode<br/>byok › metered › shared › host-session › local]

Wildcard deny: If the system or org policy sets "*": { "metered": { "allowed": false } }, no child scope can re-open metered access for that wildcard key, even by writing an explicit model-specific allow. The wildcard deny at the parent is final.

Setting access constraints

Use the Model Access Matrix screen at /admin/model-access or the declarative API:

# Restrict an org to BYOK only
curl -X PUT https://rensei.ai/api/org/{orgId}/model-access \
  -H "Authorization: Bearer <operator-token>" \
  -d '{"matrix":{"*":{"metered":{"allowed":false},"shared":{"allowed":false}}}}'

See Model Access Matrix for the full API reference.

Reverse-lookup / blast-radius

Before narrowing a policy at any scope, use the blast-radius trace to see what would be affected:

POST /api/admin/model-access/trace

The trace returns:

The admin screen's Trace impact button triggers this call automatically before each save.

Soft-warn vs fail-closed

Access constraints have two enforcement points:

Soft-warn (save / assign): When an operator saves a profile or assigns it to a dispatch key, the platform checks the effective allowed modes for that scope. If any mode in the profile's auth_modes conflicts with the effective matrix, an advisory warning is returned. The write is NOT blocked. This is informational only.

Fail-closed (dispatch): At dispatch time, the resolver throws AccessDeniedError or AUTHMODES_UNSATISFIABLE if no permitted mode exists. There is no silent fallback. A dispatch that violates the access policy never succeeds.

Related pages

• Model Access Matrix - unified access + cost matrix, cascade-narrowing, blast-radius trace, declarative API
• Model Profiles - set-based auth_modes and audience dimension
• Auth Modes - preference order and scope narrowing
• Billing - Stripe subscription and usage
• Members and RBAC - inviting members, role assignments
• Directory Sync - SCIM provisioning and group mapping
• SSO - WorkOS SAML/OIDC setup
• Credential Overview - how credentials are org- and project-scoped
• Workflow Environments - env-aware $ref resolution