Roles and permissions

Access control in Togul is permission-based. Each role carries a set of permission strings. When a user performs an action, Togul checks whether their role includes the required permission.

Organization roles
Project roles

Organization roles govern access to org-level resources: members, billing, exports, projects, and flags.

Built-in roles

Togul ships with five system roles. System roles have is_system: true and cannot be modified or deleted.

Role	Typical use
`owner`	Full access, including billing and organization deletion
`admin`	Full access except organization deletion
`developer`	Flag and rule management
`analyst`	Read-only access to flags, rules, and usage
`viewer`	Read-only access to flags

Custom roles

Create a custom role with POST /api/v1/roles. Requires the roles.create permission.

curl -X POST http://localhost:8080/api/v1/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "release_manager",
    "name": "Release Manager",
    "permissions": ["flags.read", "flags.write", "rules.read", "rules.write"]
  }'

Response:

{
  "role": {
    "id": "role-uuid-here",
    "key": "release_manager",
    "name": "Release Manager",
    "is_system": false,
    "permissions": ["flags.read", "flags.write", "rules.read", "rules.write"]
  }
}

Update a custom role’s name or permissions with PATCH /api/v1/roles/{id} (requires roles.update). Delete it with DELETE /api/v1/roles/{id} (requires roles.delete).

A role that is currently assigned to one or more members cannot be deleted. The API returns 409 Conflict. Remove all member assignments first.

Role schema

Field	Type	Description
`id`	string (UUID)	Unique role identifier
`key`	string	Machine-readable key (e.g. `release_manager`)
`name`	string	Human-readable display name
`is_system`	boolean	`true` for built-in roles; `false` for custom roles
`permissions`	string[]	Array of permission strings granted by this role

Invitations

When you invite a user with POST /api/v1/invitations, you specify a role_id. The invitation assigns that role to the new member when accepted.If the invited email does not belong to an existing Togul account, you can create the account inline by including name and password in the POST /api/v1/invitations/accept request body.

Project roles govern access within a specific project. A user can have a different role in each project they belong to, independent of their organization-level role.Add a member to a project with POST /api/v1/projects/{project_id}/members. The user must already be an organization member.

curl -X POST http://localhost:8080/api/v1/projects/$PROJECT_ID/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-uuid-here",
    "role_id": "role-uuid-here"
  }'

Update a project member’s role with PATCH /api/v1/projects/{project_id}/members/{member_id} (requires project_members.write). Remove a member with DELETE (requires project_members.remove).Project member permissions (project_members.read, project_members.write, project_members.remove) are separate from organization member permissions.

Available permissions

Organization

Permission	Description
`org.read`	View organization details
`org.update`	Update organization name and settings
`org.delete`	Delete the organization

Members

Permission	Description
`members.read`	List organization members and pending invitations
`members.invite`	Create and revoke invitations
`members.update`	Change a member’s role
`members.remove`	Remove a member from the organization

Roles

Permission	Description
`roles.read`	List all roles
`roles.create`	Create a custom role
`roles.update`	Update a custom role
`roles.delete`	Delete a custom role

Projects

Permission	Description
`projects.read`	List and view projects
`projects.write`	Create and update projects
`projects.delete`	Delete a project

Environments

Permission	Description
`environments.read`	View environments
`environments.write`	Create environments
`environments.delete`	Delete environments

Flags

Permission	Description
`flags.read`	List and view flags
`flags.write`	Create and update flags
`flags.delete`	Delete flags

Rules

Permission	Description
`rules.read`	View rules
`rules.write`	Create and update rules
`rules.delete`	Delete rules

API keys

Permission	Description
`api_keys.read`	List API keys
`api_keys.write`	Create and rotate API keys
`api_keys.delete`	Revoke API keys

Billing

Permission	Description
`billing.read`	View subscription details and create portal sessions
`billing.write`	Create checkout sessions and modify subscriptions

Exports

Permission	Description
`exports.write`	Create and list data exports

Usage

Permission	Description
`usage.read`	View usage rollups

Project members

Permission	Description
`project_members.read`	List project members
`project_members.write`	Add members and update their project roles
`project_members.remove`	Remove members from a project

Get Started

Core Concepts

Guides

Account & Billing

Built-in roles

Custom roles

Role schema

Invitations

Available permissions

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Account & Billing

​Built-in roles

​Custom roles

​Role schema

​Invitations

​Available permissions

Build docs developers (and LLMs) love

Built-in roles

Custom roles

Role schema

Invitations

Available permissions