Skip to content
/
Role
Last updated

Role object

🔨 In Development — This section is still being developed and may change.
The Role object defines permission sets that can be assigned to users within organizations. Freddy supports both global base roles (available to all organizations) and organization-specific custom roles.

Properties

Identity

id string required

Unique role identifier. Format: rol_ followed by alphanumeric characters.

name string required

Role name (e.g., member, admin, owner).

description string | null optional

Human-readable description of the role and its purpose.

Scope

organization_id string | null optional

Reference to the Organization this role belongs to. null for global base roles available to all organizations.

Permissions

permissions object required

JSON object defining the role's permissions. Structure varies by role type.

Base permissions:

  • read: View organization data
  • write: Create and modify resources
  • delete: Delete resources
  • manage_users: Add, remove, and manage organization members
  • manage_billing: Access billing and payment settings
  • manage_organization: Modify organization settings

Role Type

is_base_role boolean required

Whether this is a global base role (Member, Admin, Owner). Default: false.

is_custom boolean required

Whether this is a custom organization-specific role. Default: false.

can_be_deleted boolean required

Whether the role can be deleted. Base roles cannot be deleted. Default: true.

Status & Visibility

is_active boolean required

Whether the role is active and can be assigned. Default: true.

hidden boolean required

Whether the role is hidden from regular endpoints. Default: false.

aitronos_only boolean required

Whether the role is restricted to Aitronos team members only. Default: false.

Timestamps

created_at string required

Timestamp when the role was created. Format: ISO 8601 datetime string.

updated_at string required

Timestamp when the role was last updated. Format: ISO 8601 datetime string.

Base Roles

Freddy provides three mandatory base roles for every organization:

Member

Basic member with read-only access to organization resources.

Admin

Administrator with full access to manage users, data, and organization settings (except billing).

Owner

Organization owner with complete control including billing and organization management.

Custom Roles

Organizations can create custom roles with tailored permission sets to match their specific needs.

Base Role: Owner

{
  "id": "rol_owner_base_001",
  "name": "owner",
  "description": "Organization owner with complete control over all aspects including billing and user management",
  "organization_id": null,
  "permissions": {
    "read": true,
    "write": true,
    "delete": true,
    "manage_users": true,
    "manage_billing": true,
    "manage_organization": true
  },
  "is_base_role": true,
  "is_custom": false,
  "can_be_deleted": false,
  "is_active": true,
  "hidden": false,
  "aitronos_only": false,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Base Role: Admin

{
  "id": "rol_admin_base_002",
  "name": "admin",
  "description": "Administrator with full access to manage users, financial data, and organization settings",
  "organization_id": null,
  "permissions": {
    "read": true,
    "write": true,
    "delete": true,
    "manage_users": true
  },
  "is_base_role": true,
  "is_custom": false,
  "can_be_deleted": false,
  "is_active": true,
  "hidden": false,
  "aitronos_only": false,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Base Role: Member

{
  "id": "rol_member_base_003",
  "name": "member",
  "description": "Basic member with access to view financial data and perform standard operations",
  "organization_id": null,
  "permissions": {
    "read": true,
    "write": false,
    "delete": false
  },
  "is_base_role": true,
  "is_custom": false,
  "can_be_deleted": false,
  "is_active": true,
  "hidden": false,
  "aitronos_only": false,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Custom Role: Developer

{
  "id": "rol_dev_custom_abc123",
  "name": "developer",
  "description": "Developer role with API access and resource management",
  "organization_id": "ORG_A1B2C3D4E5F6G7H8",
  "permissions": {
    "read": true,
    "write": true,
    "delete": false,
    "manage_api_keys": true,
    "access_logs": true
  },
  "is_base_role": false,
  "is_custom": true,
  "can_be_deleted": true,
  "is_active": true,
  "hidden": false,
  "aitronos_only": false,
  "created_at": "2025-01-10T09:00:00Z",
  "updated_at": "2025-01-15T14:30:00Z"
}
Previous page
Next page