Skip to main content

​
Overview

Piper uses a flexible Role-Based Access Control (RBAC) system to manage what users and API tokens can do within an organization. Each organization has roles that grant specific permissions, and users are assigned a single role within each organization.

​
Organization Ownership

Every organization has a single owner - the user who has ultimate control over the organization. Organization ownership is tracked via owner_user_id and is separate from RBAC roles. The organization owner:
  • Automatically has all permissions regardless of assigned role
  • Is the only user who can delete the organization
  • Is the only user who can transfer ownership to another user
  • Can perform billing and subscription management
Ownership is not a role - it’s a separate property of the organization. The owner is typically assigned the Admin role, but their ownership status grants them all permissions automatically, even if their role wouldn’t normally allow it.

​
System Roles

Every organization comes with three built-in system roles that cannot be modified or deleted:
RoleDescriptionKey Capabilities
AdminOrganization managementManage members, settings, tokens, and all content
EditorContent creationCreate and edit agents, knowledge, and tests
ViewerRead-only accessView resources and invoke agents

​
Role Permission Matrix

The following table shows exactly which permissions each system role includes. Note that the organization owner (regardless of role) has all permissions.
PermissionAdminEditorViewer
Organization
org:read✓✓✓
org:update✓
org:delete
org:billing
Members
members:read✓✓✓
members:invite✓
members:update✓
members:remove✓
Agents
agents:read✓✓✓
agents:create✓✓
agents:update✓✓
agents:delete✓✓
Knowledge
knowledge:read✓✓✓
knowledge:create✓✓
knowledge:update✓✓
knowledge:delete✓✓
Tests
tests:read✓✓✓
tests:create✓✓
tests:update✓✓
tests:delete✓✓
tests:execute✓✓
API Tokens
tokens:read✓
tokens:create✓
tokens:revoke✓
Roles
roles:read✓✓✓
roles:create✓
roles:update✓
roles:delete✓
Runtime
runtime:invoke✓✓✓
The organization owner always has org:delete and org:billing permissions, even though no system role grants them. These are ownership-specific permissions.

​
Permissions

Permissions follow a resource:action format. For example, agents:create allows creating agents.

​
Permission Categories

PermissionDescription
org:readView organization details
org:updateUpdate organization settings
org:deleteDelete the organization (owner only)
org:billingManage billing and subscription (owner only)
PermissionDescription
members:readView organization members
members:inviteInvite new members
members:updateUpdate member roles
members:removeRemove members
PermissionDescription
agents:readView agents
agents:createCreate new agents
agents:updateModify existing agents
agents:deleteDelete agents
PermissionDescription
knowledge:readView collections and documents
knowledge:createCreate collections and upload documents
knowledge:updateModify collections and documents
knowledge:deleteDelete collections and documents
PermissionDescription
tests:readView test configurations
tests:createCreate test suites
tests:updateModify test configurations
tests:deleteDelete tests
tests:executeRun test executions
PermissionDescription
tokens:readView API tokens
tokens:createCreate new API tokens
tokens:revokeRevoke existing tokens
PermissionDescription
roles:readView roles and their permissions
roles:createCreate custom roles
roles:updateModify custom roles
roles:deleteDelete custom roles
PermissionDescription
runtime:invokeInvoke agents and get responses

​
Custom Roles

Admins can create custom roles with specific permission sets: 
curl -X POST "https://api.letpiper.com/v1/orgs/{org_id}/roles" \
  -H "Authorization: Bearer pat_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Can view agents and invoke them but not modify",
    "permissions": ["org:read", "agents:read", "runtime:invoke"]
  }'

​
Wildcard Permissions

Use wildcards to grant all permissions in a category:
  • agents:* - All agent permissions (read, create, update, delete)
  • * - All permissions (Admin role uses this)

​
Role Assignment

Each user has one role per organization. When inviting a user, you select which role they should have:
  • Admin - For users who need to manage the organization
  • Editor - For users who create content (agents, knowledge, tests)
  • Viewer - For users who only need to view and use existing resources
If you need more granular permissions, create a custom role with the specific permissions required.

​
Platform Token Permissions

API tokens are created with explicit permissions rather than roles. The token can have any subset of the creating user’s permissions: 
curl -X POST "https://api.letpiper.com/v1/orgs/{org_id}/platform-tokens" \
  -H "Authorization: Bearer pat_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Token",
    "permissions": ["agents:read", "runtime:invoke"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'
Tokens cannot have more permissions than the user who creates them. If you try to grant a permission you don’t have, the request will fail with a 403 error.

​
Dashboard Experience

The Piper dashboard automatically adapts to your permissions. You’ll only see actions and features you’re authorized to use.

​
What You’ll See by Role

RoleDashboard Experience
ViewerRead-only access. Can browse agents, knowledge, and tests but cannot create, edit, or delete. Forms are disabled.
EditorFull content creation. Can create and manage agents, knowledge, and tests. Cannot manage members or API tokens.
AdminOrganization management. Everything Editors can do, plus invite/remove members, manage API tokens, and update org settings.
OwnerFull control. Same as Admin plus the ability to delete the organization and manage billing. The owner is always shown with their assigned role (typically Admin).

​
Permission-Aware UI

  • Hidden buttons: Actions you can’t perform won’t appear. For example, Viewers won’t see “Create Agent” or “Delete” buttons.
  • Disabled forms: If you can view a resource but not edit it, form fields will be disabled.
  • Permission errors: If an action fails due to permissions (e.g., a permission was revoked mid-session), you’ll see a “Permission Denied” dialog explaining why.
If you need access to a feature you can’t see, contact your organization admin to request a role change or a custom role with the specific permissions you need.

​
Best Practices

Principle of Least Privilege

Assign users the minimum permissions they need. Start with Viewer and upgrade to Editor or Admin only as needed.

Use Custom Roles

Create custom roles for specific permission combinations rather than relying only on the three system roles.

Scope API Tokens

Create tokens with only the permissions required for their specific use case. Never use * (all permissions) for tokens.

Audit Regularly

Periodically review role assignments and remove unnecessary permissions.