Skip to main content

Roles

GET /roles​

List all roles (built-in and custom).

  • Auth required: Yes
  • Permission: roles.manage

Response

{
  "roles": [
    {
      "id": "role_abc",
      "name": "Developer",
      "description": "Access to SSH and SFTP only",
      "isBuiltin": false,
      "permissions": ["connections.create", "connections.edit_own"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET /roles/permissions​

List all available permissions grouped by category.

  • Auth required: Yes
  • Permission: roles.manage

Response

{
  "permissionGroups": {
    "connections": ["connections.create", "connections.edit_own", "..."],
    "sessions": ["sessions.view_any", "sessions.delete"],
    "users": ["users.manage"],
    "roles": ["roles.manage"],
    "audit": ["audit.view_any"],
    "settings": ["settings.manage", "settings.notifications", "settings.backup"]
  }
}

POST /roles​

Create a custom role.

  • Auth required: Yes
  • Permission: roles.manage

Request body

{
  "name": "Developer",
  "description": "SSH and SFTP access only",
  "permissions": ["connections.create", "connections.edit_own", "connections.delete_own"]
}

Response

{
  "id": "role_xyz",
  "name": "Developer",
  "description": "SSH and SFTP access only",
  "isBuiltin": false,
  "permissions": ["connections.create", "connections.edit_own", "connections.delete_own"],
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

PUT /roles/:id​

Update a role's name, description, or permissions. Built-in roles cannot have their name or description changed, but their permissions can be updated.

  • Auth required: Yes
  • Permission: roles.manage

Request body (all fields optional)

{
  "name": "Senior Developer",
  "description": "Extended access",
  "permissions": ["connections.create", "connections.edit_any"]
}

Response

{
  "id": "role_xyz",
  "name": "Senior Developer",
  "isBuiltin": false,
  "permissions": ["connections.create", "connections.edit_any"],
  "createdAt": "...",
  "updatedAt": "..."
}

POST /roles/:id/reset​

Reset a built-in role to its default permissions.

  • Auth required: Yes
  • Permission: roles.manage

Response

{
  "id": "role_abc",
  "name": "user",
  "isBuiltin": true,
  "permissions": ["connections.create", "connections.edit_own", "connections.delete_own"],
  "createdAt": "...",
  "updatedAt": "..."
}

DELETE /roles/:id​

Delete a custom role. Cannot delete built-in roles or roles that still have users assigned.

  • Auth required: Yes
  • Permission: roles.manage

Response

{ "success": true }