Permissions

Permissions define what actions can be performed on which resources.

Permission Model

interface Permission {
  id: string;
  resource: string;     // e.g., "users", "organizations"
  action: string;       // e.g., "create", "read", "update", "delete"
  description: string;
  tenantId: string;
  createdAt: Date;
}

Permission Naming Convention

Permissions follow the resource:action pattern:

users:create
users:read
users:update
users:delete
organizations:manage
roles:assign

List Permissions

Endpoint

GET /permissions

Query Parameters

Parameter	Type	Description
page	number	Page number
limit	number	Items per page
resource	string	Filter by resource
group	string	Filter by group

Response (200 OK)

{
  "data": [
    {
      "id": "perm-001",
      "resource": "users",
      "action": "create",
      "description": "Create new users"
    },
    {
      "id": "perm-002",
      "resource": "users",
      "action": "read",
      "description": "View user information"
    },
    {
      "id": "perm-003",
      "resource": "users",
      "action": "update",
      "description": "Modify user information"
    },
    {
      "id": "perm-004",
      "resource": "users",
      "action": "delete",
      "description": "Delete users"
    }
  ],
  "pagination": {
    "total": 24,
    "page": 1,
    "limit": 20,
    "totalPages": 2
  }
}

Get Permissions by Resource

Endpoint

GET /permissions?resource=users

Response

{
  "data": [
    { "id": "perm-001", "resource": "users", "action": "create" },
    { "id": "perm-002", "resource": "users", "action": "read" },
    { "id": "perm-003", "resource": "users", "action": "update" },
    { "id": "perm-004", "resource": "users", "action": "delete" }
  ]
}

Create Permission

Endpoint

POST /permissions

Request

{
  "resource": "reports",
  "action": "generate",
  "description": "Generate reports"
}

Response (201 Created)

{
  "id": "perm-025",
  "resource": "reports",
  "action": "generate",
  "description": "Generate reports",
  "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Assign Permission to Role

Endpoint

POST /roles/:roleId/permissions

Request

{
  "permissionId": "perm-025"
}

Response (200 OK)

{
  "id": "role-id",
  "name": "REPORT_VIEWER",
  "permissions": [
    { "id": "perm-025", "resource": "reports", "action": "generate" }
  ]
}

Remove Permission from Role

Endpoint

DELETE /roles/:roleId/permissions/:permissionId

Response (204 No Content)

Standard Permissions

CORTEX includes standard permissions for each resource:

User Permissions

Permission	Description
users:create	Create users
users:read	View users
users:update	Modify users
users:delete	Delete users

Organization Permissions

Permission	Description
organizations:create	Create organizations
organizations:read	View organizations
organizations:update	Modify organizations
organizations:delete	Delete organizations

Role Permissions

Permission	Description
roles:create	Create roles
roles:read	View roles
roles:update	Modify roles
roles:delete	Delete roles
roles:assign	Assign roles to users

Audit Permissions

Permission	Description
audit:read	View audit logs
audit:export	Export audit logs

Code Examples

TypeScript

interface Permission {
  id: string;
  resource: string;
  action: string;
  description: string;
}

async function listPermissions(
  accessToken: string,
  resource?: string
): Promise<Permission[]> {
  const url = new URL('http://localhost:8091/permissions');
  if (resource) url.searchParams.set('resource', resource);

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${accessToken}` },
  });
  const data = await response.json();
  return data.data;
}

async function assignPermissionToRole(
  accessToken: string,
  roleId: string,
  permissionId: string
): Promise<void> {
  await fetch(`http://localhost:8091/roles/${roleId}/permissions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
    },
    body: JSON.stringify({ permissionId }),
  });
}

cURL

# List all permissions
curl http://localhost:8091/permissions \
  -H "Authorization: Bearer <access-token>"

# List user permissions
curl "http://localhost:8091/permissions?resource=users" \
  -H "Authorization: Bearer <access-token>"

# Create permission
curl -X POST http://localhost:8091/permissions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"resource": "reports", "action": "generate", "description": "Generate reports"}'

# Assign permission to role
curl -X POST http://localhost:8091/roles/role-id/permissions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"permissionId": "perm-025"}'