# List roles

List all roles available for an organization, including both global and organization-specific roles.

## Path parameters

- **organization_id** `string` *Required*
  - Organization ID (org_ prefixed string)


## Query parameters

- **include_global** `boolean` *Optional*
  - Include global roles in the response
  - Default: `true`


## Returns

Array of [Role](#role-object) objects.


```bash
curl "https://api.aitronos.com/v1/organizations/org_abc123/roles" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
org_id = "org_abc123"

response = requests.get(
    f"https://api.aitronos.com/v1/organizations/{org_id}/roles",
    headers={"X-API-Key": api_key}
)

roles = response.json()
for role in roles:
    print(f"{role['name']}: {role['description']}")
```


```javascript
const orgId = "org_abc123";

const response = await fetch(
  `https://api.aitronos.com/v1/organizations/${orgId}/roles`,
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

const roles = await response.json();
roles.forEach(role => {
  console.log(`${role.name}: ${role.description}`);
});
```

**Response:**

200 OK

```json
[
  {
    "id": "role_member",
    "name": "Member",
    "description": "Standard member with basic access",
    "permissions": {},
    "is_base_role": true,
    "is_custom": false,
    "organization_id": null
  },
  {
    "id": "role_admin",
    "name": "Admin",
    "description": "Administrator with full access",
    "permissions": {},
    "is_base_role": true,
    "is_custom": false,
    "organization_id": null
  },
  {
    "id": "role_owner",
    "name": "Owner",
    "description": "Organization owner with complete control",
    "permissions": {},
    "is_base_role": true,
    "is_custom": false,
    "organization_id": null
  }
]
```

401 Unauthorized

```json
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required",
    "system_message": "User authentication required",
    "type": "client_error",
    "status": 401,
    "trace_id": "abc-123-def",
    "timestamp": "2025-12-07T10:30:00Z"
  }
}
```

403 Forbidden

```json
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_ACCESS_DENIED",
    "message": "You are not a member of this organization",
    "system_message": "Organization access denied",
    "type": "client_error",
    "status": 403,
    "details": {
      "organization_id": "org_abc123"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-12-07T10:30:00Z"
  }
}
```

## Role object


```json
{
  "id": "role_abc123",
  "name": "Admin",
  "description": "Administrator with full access",
  "permissions": {},
  "is_base_role": true,
  "is_custom": false,
  "organization_id": null
}
```