Authorization & Permissions

ProxifAI uses a layered authorization system combining PostgreSQL Row-Level Security (RLS) for tenant isolation with a granular RBAC permission model for fine-grained access control.

How It Works

Every API request passes through three authorization layers:

Authentication — validates JWT or Personal Access Token
Tenant Isolation — PostgreSQL RLS automatically scopes all queries to the current organization
Permission Check — each handler verifies the user has the required permission via their roles

Tenant isolation is automatic and enforced at the database level. Even if a permission check were bypassed, RLS prevents any cross-organization data access.

System Roles

Three built-in roles are created for every organization:

Owner

Full access to every feature, including admin operations and organization deletion.

Admin

Same as Owner, except no admin.access. Cannot access super-admin endpoints or delete the organization.

Member

Day-to-day contributor access. Can create issues, write code, and run workflows. Cannot delete issues, manage projects, change settings, or manage integrations.

What Members CAN do	What Members CANNOT do
Create and edit issues	Delete issues
Read projects	Create, edit, or delete projects
Read and write code	Manage integrations
Create and run workflows	Edit or delete workflows
Use AI chat and agents	Manage agent configurations
Read teams and members	Create, edit, or delete teams

Permission Reference

35 granular permissions organized in 11 groups (including the four cloud permissions added with ProxifAI Cloud).

Issues

Permission	Description
`issues.read`	View issues, labels, sprints, time entries
`issues.create`	Create issues, tickets, and feature requests
`issues.edit`	Update issues, manage labels, comments, views, and time entries
`issues.delete`	Delete issues, tickets, and feature requests
`issues.dispatch`	Dispatch issues to AI agents for automated resolution

Projects

Permission	Description
`projects.read`	View projects, initiatives, and documents
`projects.create`	Create projects and initiatives
`projects.edit`	Update projects, sprints, initiatives, and documents
`projects.delete`	Delete projects, sprints, initiatives, and documents
`projects.members`	Manage project membership (add/remove members, change roles)

Members

Permission	Description
`members.read`	View organization members, roles, and permission definitions
`members.invite`	Invite new members to the organization
`members.edit`	Edit member roles, create/update/delete custom roles, set permission overrides
`members.remove`	Remove members from the organization

Teams

Permission	Description
`teams.read`	View teams and team members
`teams.create`	Create new teams
`teams.edit`	Update teams, add/remove team members
`teams.delete`	Delete teams

Settings

Permission	Description
`settings.read`	View workspace settings, custom fields, model providers, event types
`settings.edit`	Edit workspace settings, manage secrets, model providers, custom fields, event types, SLA policies, canned responses, ticket tags, gateway rate limits and budgets, client management

Code

Permission	Description
`code.read`	Read repositories, branches, commits, files, pipeline runs and logs
`code.write`	Push code, create/delete branches, create/merge PRs, manage releases and assets, dispatch/cancel pipelines, manage pipeline secrets/variables, configure branch protection rules, push rules, approval rules, protected tags, and deploy keys

Workflows

Permission	Description
`workflows.read`	View workflows, triggers, templates, and execution history
`workflows.create`	Create workflows, triggers, and templates; import workflows
`workflows.edit`	Update, delete, publish, and promote workflows, triggers, and templates
`workflows.run`	Execute workflows, cancel/retry/resume executions, test triggers

Integrations

Permission	Description
`integrations.read`	View integrations and webhook configurations
`integrations.manage`	Create, update, delete integrations; manage inbound/outbound webhooks and Slack channel mappings; verify credentials

Agents

Permission	Description
`agents.read`	View AI agent configurations and execution history
`agents.manage`	Create, update, and delete AI agent configurations

Cloud (ProxifAI Cloud)

Permission	Description
`cloud.read`	View virtual clusters, workloads, deployments
`cloud.exec`	Open shell sessions and run commands inside cloud workloads
`cloud.query`	Query cloud-hosted databases via the dump/query endpoints
`cloud.manage`	Create, edit, and delete clusters; deploy and scale workloads

Admin

Permission	Description
`admin.access`	Super-admin access: manage all organizations, view all users via `/api/v1/admin/*`

Custom Roles

Create custom roles with any subset of the 35 permissions from Settings > Roles.

A custom role is a named collection of permissions:

{
  "name": "Reviewer",
  "description": "Can review code and manage PRs",
  "permissions": [
    "code.read",
    "code.write",
    "issues.read",
    "issues.edit"
  ]
}

Example custom roles:

Role	Permissions	Use Case
Triage Lead	`issues.read`, `issues.edit`, `projects.read`	Prioritize and assign issues without code access
CI Operator	`code.read`, `workflows.run`	Trigger and monitor pipelines without editing definitions
External Contributor	`code.read`, `code.write`, `issues.read`	Push code and read issues, nothing else
Security Auditor	`code.read`, `settings.read`, `members.read`	Read-only access to code, settings, and member info

Per-User Permission Overrides

Individual users can have permissions explicitly granted or denied, regardless of their role assignments. Overrides are evaluated first and take priority.

Grant override — user gets the permission even if no role provides it
Deny override — user loses the permission even if a role provides it

Manage overrides via Settings > Members > [member] > Permission Overrides or the API:

PUT /api/v1/org/members/{userId}/permissions

Project-Level Roles

Beyond org-level permissions, users have per-project roles. Three values, defined in models.go:

Role	Description
`viewer`	Read-only access to the project
`member`	Standard contributor
`lead`	Can manage project settings (members, status, repo links)

Users with the projects.edit org-level permission bypass project-level role checks entirely.

Personal Access Tokens

PATs provide scoped access for CI/CD, scripts, and the CLI. They use a separate scope system optimized for git and API access patterns.

Token Format

Tokens use the pfai_ prefix followed by 40 hex characters:

pfai_a1b2c3d4e5f6...

The full token value is shown only once at creation. It is stored as a SHA-256 hash and cannot be retrieved later.

Token Scopes

Scope	Description	Implies
`read`	Broad read access	All `*:read` scopes
`write`	Broad write access	`read` + all `*:write` scopes
`repo:read`	Read repositories, branches, commits, files
`repo:write`	Push code, create branches, manage releases	`repo:read`
`issues:read`	Read issues and comments
`issues:write`	Create and update issues	`issues:read`
`pr:read`	Read pull requests and reviews
`pr:write`	Create, merge PRs and submit reviews	`pr:read`
`admin:read`	Read admin-level data
`admin:write`	Modify admin-level data	`admin:read`
`pipeline`	Trigger and manage CI/CD pipelines

Scope Hierarchy

The write scope includes everything. Fine-grained write scopes imply their corresponding read scope:

write ⊇ read ⊇ repo:read, issues:read, pr:read, admin:read
write ⊇ repo:write, issues:write, pr:write, admin:write, pipeline
repo:write ⊇ repo:read
issues:write ⊇ issues:read
pr:write ⊇ pr:read
admin:write ⊇ admin:read

Git Authentication with PATs

Use a PAT as the password in Git HTTP basic auth (username is ignored):

git clone https://x-token:[email protected]/org/repo.git

Operation	Minimum Scope
Clone/fetch (public repo)	No token required
Clone/fetch (private repo)	`read` or `repo:read`
Push	`write` or `repo:write`
Push to archived repo	Rejected (403)

CLI Commands

# Authentication
pfai auth login                  # OAuth login via browser
pfai auth status                 # Show current auth state
pfai auth token                  # Display JWT claims

# Roles & permissions
pfai org roles                   # List roles in your org
pfai org members                 # List members with roles
pfai org features                # List enabled features

# Personal access tokens
pfai token list                  # List your PATs
pfai token create --name "CI" --scopes read,pipeline
pfai token delete tok_abc123

# Check your permissions
pfai api GET /me/permissions     # Raw API call to see effective permissions

API Reference

Permission Management

GET    /api/v1/me/permissions                     # Your effective permissions
GET    /api/v1/org/permissions                     # All permission definitions
GET    /api/v1/org/roles                           # List roles
POST   /api/v1/org/roles                           # Create role
PATCH  /api/v1/org/roles/{id}                      # Update role
DELETE /api/v1/org/roles/{id}                      # Delete role
PUT    /api/v1/org/members/{userId}/roles          # Assign roles
GET    /api/v1/org/members/{userId}/permissions    # User's permissions
PUT    /api/v1/org/members/{userId}/permissions    # Set overrides

Token Management

GET    /api/v1/tokens                # List PATs
POST   /api/v1/tokens                # Create PAT
PATCH  /api/v1/tokens/{id}           # Update PAT
DELETE /api/v1/tokens/{id}           # Revoke PAT