What is an organization?
An organization is the root container for all Togul resources. Every project, environment, flag, API key, member, role, and billing subscription belongs to exactly one organization. When you call the API, your JWT token is scoped to a specific organization — all read and write operations apply within that organization’s context.
Automatic creation on registration
When you register a new account, Togul automatically creates an organization on your behalf and assigns you as its owner. You do not need to create an organization manually to get started.
Belonging to multiple organizations
A single user account can be a member of multiple organizations. This is common for consultants, contractors, or users who manage separate product lines under different organizations.
To switch between organizations, call POST /api/v1/me/switch-organization with the target organization_id and a valid refresh_token. The response returns a new organization-scoped JWT token and rotated refresh token.
{
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"refresh_token": "<your-refresh-token>"
}
The organization context is encoded in the JWT token. All subsequent API requests use the organization encoded in the token — you do not pass an organization identifier on each request.
Deletion constraints
You cannot delete an organization if it is the last one you belong to. The API enforces that you must be a member of at least one other organization before deletion is allowed. This prevents users from being left in a state with no organization.
Deleting an organization requires the org.delete permission and uses a soft delete: all data is retained in the database but becomes inaccessible through the API. This supports data recovery and audit requirements.
Soft-deleted organization data is inaccessible via the API immediately after deletion. Contact support if you need to recover soft-deleted data.
Schemas
Two representations of an organization are returned by different endpoints.
OrganizationSummary
Returned in list contexts, session payloads, and the GET /api/v1/me response. Includes the caller’s role in that organization.
| Field | Type | Description |
|---|
id | UUID | Unique organization identifier |
slug | string | URL-safe identifier derived from the organization name |
name | string | Display name |
role | string | Caller’s role: owner, admin, developer, analyst, or viewer |
OrganizationDetail
Returned by GET /api/v1/organizations/current and PATCH /api/v1/organizations/current. Includes timestamps but not the caller’s role.
| Field | Type | Description |
|---|
id | UUID | Unique organization identifier |
slug | string | URL-safe identifier |
name | string | Display name |
created_at | datetime | ISO 8601 creation timestamp |
updated_at | datetime | ISO 8601 last-updated timestamp |
Endpoints
| Method | Endpoint | Permission | Description |
|---|
POST | /api/v1/organizations | Authenticated user (no org permission required) | Create a new organization |
GET | /api/v1/organizations/current | org.read | Get details of the current organization |
PATCH | /api/v1/organizations/current | org.update | Update the name of the current organization |
DELETE | /api/v1/organizations/{id} | org.delete | Soft-delete an organization by ID |
POST | /api/v1/me/switch-organization | Authenticated user | Switch the active organization context |
Required permissions
org.read — Read organization detailsorg.update — Update organization nameorg.delete — Delete an organization (subject to last-org constraint)
Creating a new organization is a user-level action and does not require any existing organization permission.