---
title: "Create Custom Role"
method: POST
path: "/api/v1/roles"
tags: ["Team Management"]
---

# Create Custom Role

`POST /api/v1/roles`

Creates a custom role with a per-category permission matrix. Custom roles are available on the Enterprise plan. Every category is at least 'view' — omitted categories default to 'view'. The role name must be unique in your organization and must not collide with a system role name; the permission matrix must not duplicate an existing role's. Requires a global API key.

## Request body

- CreateRoleRequest — Request body for creating a custom role
  - `name` string, required — Display name of the role. Must be unique in your organization (case-insensitive) and must not collide with a system role name.
  - `permissions` PermissionMatrix, required — Per-category access levels for a role. Every category is at least 'view'; categories omitted on create/update default to 'view'.
    - `content` 'none' | 'view' | 'write'
    - `prompts` 'none' | 'view' | 'write'
    - `competitors` 'none' | 'view' | 'write'
    - `analytics` 'none' | 'view' | 'write'
    - `integrations` 'none' | 'view' | 'write'
    - `brand_knowledge` 'none' | 'view' | 'write'
    - `team` 'none' | 'view' | 'write'
    - `billing` 'none' | 'view' | 'write'
    - `api` 'none' | 'view' | 'write'
    - `organization` 'none' | 'view' | 'write'

## Response `201`

Role created successfully

- object
  - `success` boolean, required
  - `role` Role, required — A role available in your organization — a built-in system role or a custom role.
    - `role_id` string, required — Unique identifier of the role. Usable as `role_id` in invites and member role updates. Built-in system roles use GUID-shaped sentinel IDs (e.g. `00000000-0000-0000-0000-000000000001`), not RFC 4122 UUIDs.
    - `name` string, required — Display name of the role
    - `slug` string, required — Normalized name of the role (e.g. 'admin', 'content-manager')
    - `is_system` boolean, required — Whether this is a built-in system role (Admin, Editor, Viewer, Billing). System roles cannot be edited or deleted.
    - `permissions` PermissionMatrix, required — Per-category access levels for a role. Every category is at least 'view'; categories omitted on create/update default to 'view'.
      - `content` 'none' | 'view' | 'write'
      - `prompts` 'none' | 'view' | 'write'
      - `competitors` 'none' | 'view' | 'write'
      - `analytics` 'none' | 'view' | 'write'
      - `integrations` 'none' | 'view' | 'write'
      - `brand_knowledge` 'none' | 'view' | 'write'
      - `team` 'none' | 'view' | 'write'
      - `billing` 'none' | 'view' | 'write'
      - `api` 'none' | 'view' | 'write'
      - `organization` 'none' | 'view' | 'write'
    - `created_at` string, required — When the role was created

## Other responses

- `400` — Bad request - Invalid role name or permissions
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Global API key required, or the organization is not on the Enterprise plan
- `409` — Conflict - Role name already exists or permissions duplicate an existing role's
- `500` — Internal server error

---

[API](https://skmtc.net/athenahq/apis/athenahq-api.md) · [All operations](https://skmtc.net/athenahq/apis/athenahq-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/athenahq/athenahq-api/revisions/6c5d71622cb9/schema)