API Permissions Reference (ADR-092)

Version: 1.0.0 Base URL: https://api.coditect.ai/api/v1 ADR: ADR-092 Enhanced RBAC Permission System

Overview

This document specifies the required permissions for each API endpoint following the ADR-092 Enhanced RBAC Permission System. All authenticated endpoints enforce permission checks via the PermissionService.

Permission Categories

Category	Description	Permission Codes
users	User management	list, view, create, update, delete, invite, remove
tenants	Tenant administration	list, view, create, update, delete, manage, transfer
teams	Team management	list, view, create, update, delete, manage
projects	Project management	list, view, create, update, delete, manage
licenses	License management	list, view, create, update, delete, assign, manage
billing	Billing operations	view, manage, export
workstations	Cloud workstations	list, view, create, update, delete, manage
analytics	Analytics & reporting	view, export, downloads
issues	Issue tracking	list, view, create, update, delete, assign, manage
feedback	Feedback management	list, view, create, update, delete, assign
admin	System administration	panel, provisioning, settings, downloads:approve, audit

---

Authentication Endpoints

Base Path: /api/v1/auth/

Method	Endpoint	Permission	Description
POST	/register/	None (public)	Register new user
POST	/login/	None (public)	Obtain JWT tokens
POST	/token/	None (public)	Obtain JWT token pair
POST	/token/refresh/	None (public)	Refresh access token
POST	/token/verify/	None (public)	Verify token validity
GET	/me/	Authenticated	Get current user info

Two-Factor Authentication

Base Path: /api/v1/auth/2fa/

Method	Endpoint	Permission	Description
GET	/status/	Authenticated	Get 2FA status
POST	/setup/	Authenticated	Initialize 2FA setup
GET	/qr-code/	Authenticated	Get TOTP QR code
POST	/verify/	Authenticated	Verify 2FA setup
POST	/disable/	Authenticated	Disable 2FA
GET	/backup-codes/	Authenticated	Get backup codes
POST	/regenerate-backup-codes/	Authenticated	Regenerate backup codes
POST	/verify-code/	Authenticated	Verify single code
POST	/send-sms/	Authenticated	Send SMS verification
POST	/login-verify/	None (token-based)	Verify 2FA during login

---

User Profile

Base Path: /api/v1/profile/

Method	Endpoint	Permission	Description
GET	/	Authenticated	Get user profile
PATCH	/	Authenticated	Update user profile

---

Tenant Management

Base Path: /api/v1/tenants/

Method	Endpoint	Permission	Description
GET	/	Authenticated	List user's tenant memberships
POST	/{tenant_id}/switch/	Authenticated	Switch active tenant context
GET	/{tenant_id}/members/	users:list	List tenant members
POST	/{tenant_id}/members/	users:invite	Add tenant member
GET	/{tenant_id}/members/{id}/	users:view	Get member details
PATCH	/{tenant_id}/members/{id}/	users:update	Update member role
DELETE	/{tenant_id}/members/{id}/	users:remove	Remove member

Invitations (A.12.1)

Method	Endpoint	Permission	Description
GET	/{tenant_id}/invites/	users:list	List pending invitations
POST	/{tenant_id}/invites/	users:invite	Create invitation
GET	/{tenant_id}/invites/{id}/	users:view	Get invitation details
DELETE	/{tenant_id}/invites/{id}/	users:remove	Cancel invitation
POST	/{tenant_id}/invites/{id}/resend/	users:invite	Resend invitation email

Public Invitation Accept

Method	Endpoint	Permission	Description
GET	/invites/{token}/	None (token-based)	Get invitation details
POST	/invites/{token}/accept/	None (token-based)	Accept invitation

---

Organization/Tenant API

Base Path: /api/v1/org/

Method	Endpoint	Permission	Description
GET	/current/	Authenticated	Get current tenant info
GET	/{id}/	tenants:view	Get tenant details
PATCH	/{id}/	tenants:update	Update tenant settings

---

Project Management (ADR-092)

Base Path: /api/v1/projects/

Project CRUD

Method	Endpoint	Permission	Description
GET	/	projects:list	List accessible projects
POST	/	projects:create	Create new project
GET	/stats/	projects:list	Get project statistics
POST	/bulk-status/	projects:manage	Bulk status update
GET	/{id}/	projects:view	Get project details
PATCH	/{id}/	projects:update	Update project
DELETE	/{id}/	projects:delete	Delete project
POST	/{id}/archive/	projects:manage	Archive project
POST	/{id}/restore/	projects:manage	Restore archived project
POST	/{id}/transfer/	projects:manage	Transfer ownership
POST	/{id}/pin/	projects:update	Toggle pin status

Project Members

Method	Endpoint	Permission	Description
GET	/{id}/members/	projects:view	List project members
POST	/{id}/members/	projects:manage	Add project member
PATCH	/{id}/members/{mid}/	projects:manage	Update member role
DELETE	/{id}/members/{mid}/	projects:manage	Remove member

Project Activity

Method	Endpoint	Permission	Description
GET	/{id}/activity/	projects:view	Get activity feed

Project Submodules (ADR-093)

Method	Endpoint	Permission	Description
GET	/{id}/submodules/	projects:view	List submodules
POST	/{id}/submodules/	projects:manage	Add submodule
GET	/{id}/submodules/tree/	projects:view	Get submodule tree
POST	/{id}/submodules/sync/	projects:manage	Sync all submodules
GET	/{id}/submodules/{sid}/	projects:view	Get submodule details
PATCH	/{id}/submodules/{sid}/	projects:manage	Update submodule
DELETE	/{id}/submodules/{sid}/	projects:manage	Remove submodule
POST	/{id}/submodules/{sid}/sync/	projects:manage	Sync specific submodule

Project Hierarchy (ADR-094)

Method	Endpoint	Permission	Description
GET	/{id}/hierarchy/	projects:view	List hierarchy entries
POST	/{id}/hierarchy/	projects:manage	Create hierarchy entry
GET	/{id}/hierarchy/tree/	projects:view	Get hierarchy tree
GET	/{id}/hierarchy/children/	projects:view	Get direct children
GET	/{id}/hierarchy/ancestors/	projects:view	Get ancestor chain
PATCH	/{id}/hierarchy/{hid}/	projects:manage	Update hierarchy entry
DELETE	/{id}/hierarchy/{hid}/	projects:manage	Remove hierarchy entry
GET	/hierarchy/roots/	projects:list	Get root-level projects

---

Report Management (ADR-095)

Report Templates

Base Path: /api/v1/report-templates/

Method	Endpoint	Permission	Description
GET	/	analytics:view	List report templates
POST	/	analytics:manage	Create report template
GET	/{id}/	analytics:view	Get template details
PATCH	/{id}/	analytics:manage	Update template
DELETE	/{id}/	analytics:manage	Delete template

Reports

Base Path: /api/v1/reports/

Method	Endpoint	Permission	Description
GET	/	analytics:view	List reports
POST	/	analytics:create	Create report
GET	/{id}/	analytics:view	Get report details
PATCH	/{id}/	analytics:manage	Update report
DELETE	/{id}/	analytics:manage	Delete report
POST	/{id}/run/	analytics:view	Execute report
GET	/{id}/executions/	analytics:view	List executions
GET	/{id}/executions/{eid}/	analytics:view	Get execution details
GET	/{id}/executions/{eid}/download/	analytics:export	Download output

---

System Administration

Base Path: /api/v1/admin/

Method	Endpoint	Permission	Description
GET	/stats/	analytics:view	Platform statistics
GET	/users/	users:list	List all users
GET	/users/pending-approvals/	users:list	Users pending approval
GET	/users/{id}/	users:view	User details
PATCH	/users/{id}/	users:update	Update user
POST	/users/{id}/approve/	admin:downloads:approve	Approve downloads
GET	/tenants/	tenants:list	List all tenants
GET	/tenants/{id}/	tenants:view	Tenant details
PATCH	/tenants/{id}/	tenants:manage	Update tenant
GET	/downloads/analytics/	analytics:view	Download analytics

---

Permission Management API (ADR-092)

Base Path: /api/v1/permissions/

Method	Endpoint	Permission	Description
GET	/definitions/	admin:panel	List all permissions
GET	/definitions/{id}/	admin:panel	Get permission details
GET	/role-permissions/	admin:panel	List role-permission mappings
POST	/role-permissions/	admin:settings	Create role-permission mapping
DELETE	/role-permissions/{id}/	admin:settings	Delete mapping
GET	/overrides/	admin:panel	List user overrides
POST	/overrides/	admin:settings	Create user override
DELETE	/overrides/{id}/	admin:settings	Delete override
GET	/audit-logs/	admin:audit	View audit logs
POST	/check/	Authenticated	Check permission

---

Context Sync API (ADR-080)

Base Path: /api/v1/context/

Method	Endpoint	Permission	Description
GET	/sessions/	Authenticated	List sessions
POST	/sessions/	Authenticated	Create session
GET	/sessions/{id}/	Authenticated	Get session details
GET	/sessions/{id}/summary/	Authenticated	Get session summary
GET	/activity/	Authenticated	Get activity feed
GET	/decisions/	Authenticated	List project decisions
POST	/decisions/	Authenticated	Create decision
GET	/preferences/	Authenticated	Get user preferences
PUT	/preferences/	Authenticated	Update preferences

---

Workstations API (ADR-005)

Base Path: /api/v1/workstations/

Method	Endpoint	Permission	Description
GET	/	workstations:list	List workstations
POST	/	workstations:create	Create workstation
GET	/{id}/	workstations:view	Get workstation details
PATCH	/{id}/	workstations:update	Update workstation
DELETE	/{id}/	workstations:delete	Delete workstation
POST	/{id}/start/	workstations:manage	Start workstation
POST	/{id}/stop/	workstations:manage	Stop workstation

---

License API

Base Path: /api/v1/licenses/

Method	Endpoint	Permission	Description
GET	/	licenses:list	List licenses
POST	/	licenses:create	Create license
GET	/{id}/	licenses:view	Get license details
PATCH	/{id}/	licenses:update	Update license
DELETE	/{id}/	licenses:delete	Delete license
POST	/{id}/assign/	licenses:assign	Assign to user
POST	/acquire/	Authenticated	Acquire floating seat
POST	/release/	Authenticated	Release floating seat
POST	/heartbeat/	Authenticated	Session heartbeat

---

Billing API (A.12.2)

Base Path: /api/v1/billing/

Method	Endpoint	Permission	Description
GET	/invoices/	billing:view	List invoices
GET	/invoices/{id}/	billing:view	Get invoice details
GET	/invoices/{id}/download/	billing:export	Download PDF
GET	/subscription/	billing:view	Get subscription info
PATCH	/subscription/	billing:manage	Update subscription
POST	/subscription/cancel/	billing:manage	Cancel subscription

---

Issues API (ADR-021)

Base Path: /api/v1/issues/

Method	Endpoint	Permission	Description
GET	/	issues:list	List issues
POST	/	issues:create	Create issue
GET	/{id}/	issues:view	Get issue details
PATCH	/{id}/	issues:update	Update issue
DELETE	/{id}/	issues:delete	Delete issue
POST	/{id}/assign/	issues:assign	Assign issue
POST	/{id}/comments/	issues:view	Add comment

---

Feedback API

Base Path: /api/v1/feedback/

Method	Endpoint	Permission	Description
GET	/	feedback:list	List feedback
POST	/	feedback:create	Submit feedback
GET	/{id}/	feedback:view	Get feedback details
PATCH	/{id}/	feedback:update	Update feedback
DELETE	/{id}/	feedback:delete	Delete feedback

---

Releases API (C.8)

Base Path: /api/v1/releases/

Method	Endpoint	Permission	Description
GET	/	None (public)	List releases
GET	/latest/{binary}/	None (public)	Get latest release
GET	/{id}/	None (public)	Get release details
POST	/signed-url	Authenticated + Approved	Get signed download URL

---

Commerce API (ADR-014)

Base Path: /api/v1/commerce/

Method	Endpoint	Permission	Description
GET	/products/	None (public)	List products
GET	/products/{slug}/	None (public)	Get product details
GET	/cart/	Authenticated	Get cart
POST	/cart/	Authenticated	Add to cart
DELETE	/cart/{id}/	Authenticated	Remove from cart
POST	/checkout/	Authenticated	Create checkout session
GET	/orders/	Authenticated	List orders
GET	/orders/{id}/	Authenticated	Get order details
GET	/entitlements/	Authenticated	Get entitlements

---

Platform API (ADR-080)

Base Path: /api/v1/platform/

Method	Endpoint	Permission	Description
GET	/components/	None (public)	List components
GET	/components/{id}/	None (public)	Get component details
GET	/agents/	None (public)	List agents
GET	/skills/	None (public)	List skills
GET	/commands/	None (public)	List commands

---

Role Permission Matrix

System Roles

Role	Description	Key Permissions
super_admin	Full platform access	All permissions
support	Customer support	users:, issues:, feedback:*, analytics:view
sales	Sales team	tenants:view, licenses:manage, billing:*
readonly	Read-only access	*:view, *:list only
user	Standard user	projects:view, issues:create, feedback:create

Tenant Roles

Role	Description	Key Permissions
owner	Tenant owner	All tenant-scoped permissions
admin	Tenant administrator	users:, teams:, projects:*, licenses:assign
member	Team member	projects:create, issues:create, feedback:create
viewer	Read-only member	*:view, *:list only
guest	External collaborator	projects:list, projects:view

Team Roles

Role	Description	Key Permissions
lead	Team lead	projects:manage, issues:assign
member	Team member	projects:update, issues:update
viewer	Read-only access	*:view only

---

Error Responses

401 Unauthorized

{
  "detail": "Authentication credentials were not provided."
}

403 Forbidden

{
  "error": "Permission denied: projects:delete",
  "detail": "You do not have the projects:delete permission."
}

Permission Check Implementation

All endpoints use PermissionService for RBAC checks:

from permissions.services import PermissionService

permission_service = PermissionService()
if not permission_service.check_permission(request.user, 'projects:delete'):
    return Response(
        {'error': 'Permission denied: projects:delete'},
        status=status.HTTP_403_FORBIDDEN
    )

---

References

• ADR-092: Enhanced RBAC Permission System
• ADR-093: Git Submodule Visibility
• ADR-094: Drillable Project Hierarchy
• ADR-095: Project Reporting Architecture

---

Last Updated: 2026-01-21 Author: CODITECT Team