# Role object

div
strong
🔨 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](/docs/api-reference/objects/organization-object) 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**


```json
{
  "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**


```json
{
  "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**


```json
{
  "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**


```json
{
  "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"
}
```