What is a project?
A project is a named namespace within an organization. Use projects to group the environments, feature flags, and rules that belong to a specific product, service, or team. For example, you might have a backend-api project and a mobile-app project within the same organization.
Every environment, flag, API key, and project-level member belongs to exactly one project.
Slug generation
When you create a project, Togul auto-generates a URL-safe slug from the name you provide. The slug is used as a stable identifier in the UI and is included in the project schema.
Permissions and visibility
Access to projects is controlled by the projects.read, projects.write, and projects.delete permissions.
- Owner and admin roles can see all projects in the organization.
- All other roles (developer, analyst, viewer, and custom roles) can only see projects they have been explicitly added to as a project member.
This allows you to give a developer access to a subset of projects without exposing unrelated ones.
Cascade deletion
Deleting a project permanently removes all of its dependent resources:
- Environments
- Flags
- Rules
- API keys
- Project members
Project deletion is permanent and cascades to all child resources. There is no soft delete at the project level.
Project schema
| Field | Type | Description |
|---|
id | UUID | Unique project identifier |
organization_id | UUID | The organization this project belongs to |
slug | string | Auto-generated URL-safe identifier |
name | string | Display name |
description | string | Optional description (nullable) |
created_at | datetime | ISO 8601 creation timestamp |
updated_at | datetime | ISO 8601 last-updated timestamp |
Project-level members and roles
Organization members can be added to specific projects with a project-scoped role. This is managed separately from organization-level membership.
- To add a member to a project, the user must already be an organization member.
- Each project member is assigned a
role_id that determines their permissions within the project.
- Project membership is managed via the
GET/POST /api/v1/projects/{project_id}/members and PATCH/DELETE /api/v1/projects/{project_id}/members/{member_id} endpoints, which require the project_members.write and project_members.remove permissions respectively.
Endpoints
| Method | Endpoint | Permission | Description |
|---|
GET | /api/v1/projects | projects.read | List projects (visibility depends on role) |
POST | /api/v1/projects | projects.write | Create a new project |
GET | /api/v1/projects/{project_id} | projects.read | Get a single project |
PATCH | /api/v1/projects/{project_id} | projects.write | Update project name or description |
DELETE | /api/v1/projects/{project_id} | projects.delete | Delete a project and all its resources |