An organization is the top-level account container in Underlayer. It groups one or more workspaces under a shared billing plan, membership roster, and access policy. Think of an organization as your company or team account, and workspaces as the isolated environments inside it.

Organizations vs. workspaces

• Organization: owns the billing subscription, sets the tier limits, and defines the access policy that applies to all its workspaces.
• Workspace: the runtime isolation unit where tasks, cron jobs, API keys, and activity logs live. Every workspace belongs to exactly one organization.

Organization slug

Like workspaces, organizations have a unique slug chosen at creation time. It appears in dashboard URLs and in organization-scoped API paths:

GET /api/v1/organizations/{organization_id}
GET /api/v1/organizations/{organization_id}/workspaces
GET /api/v1/organizations/{organization_id}/members

Roles

Every organization member has one of the following roles:

• Owner: full control over billing, members, policy, workspaces, and organization settings. Receives usage metrics and billing notifications.
• Admin: can manage members, invitations, workspaces, and the organization policy. Cannot access billing.
• Member: access is governed by the organization policy. By default members can view workspaces they belong to but cannot create new ones, invite others, or touch API keys and secrets unless the policy explicitly allows it.

Access policy

Organization admins and owners can configure a fine-grained policy that controls what regular members are allowed to do across all workspaces:

• members_can_invite: allow members to send workspace invitations.
• members_can_create_api_keys: allow members to create workspace API keys.
• members_can_create_secrets: allow members to add environment variable secrets.
• members_can_create_workspaces: allow members to create new workspaces inside the organization.
• members_can_delete_tasks: allow members to delete tasks and cron jobs.
• members_can_manage_integrations: allow members to configure integrations.

All policy flags default to false. Update them from Settings → Organization → Permissions.

Inviting members

1. Go to Settings → Organization → Members
2. Click Invite member
3. Enter the email address, choose an organization role, and choose the default workspace role they will receive when added to a workspace
4. The invitee receives an email with a join link

Tiers and limits

The organization tier (e.g. free, startup, scaleup, unicorn) determines execution quotas and the maximum number of workspaces. Usage metrics (monthly executions and storage) are visible to owners on the organization detail page.

Creating an organization

Organizations are created from the dashboard using your signed-in session. This endpoint is not an API-key workflow. In practice, create organizations from Settings and then manage workspaces, members, and billing from there.

POST /api/v1/organizations  (JWT session auth)

{
  "name": "Acme Corp"
}

The caller becomes the owner of the new organization. A slug is auto-generated from the name and can be updated later via PATCH /api/v1/organizations/{organization_id}.