---
title: "Create"
method: POST
path: "/admin/roles"
tags: ["roles"]
---

# Create

`POST /admin/roles`

## Request

- Base URL: `https://api.instruxi.dev/api/v1/enforcer`
- URL: `https://api.instruxi.dev/api/v1/enforcer/admin/roles`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `X-API-Key`

Creates a custom role with an arbitrary permission grant. System-admin (platform-only) gated — there is no separate escalation fence because only a caller who already holds cross_tenant (the maximum grant) can reach this route at all. slug must match ^[a-z][a-z0-9_]{1,49}$ (mixed case is lowercased, not rejected) and may not collide with a built-in slug (admin, tenant_admin, developer, user), which returns 409.

## Request body

- InternalDeliveryHttpHandlerCreateRoleRequest
  - `description` string
  - `name` string
  - `permissions` InternalDeliveryHttpHandlerPermissionsBody
    - `admin_managed` boolean
    - `cross_tenant` boolean
    - `mpp_ops` boolean: MPPOps grants the read-only MPP deposit-intent operator views (cross-tenant). It moves no money.
    - `tenant_manage` boolean
    - `tenant_read` boolean
    - `tenant_write` boolean
  - `slug` string

## Response `201`

Created

- InternalDeliveryHttpHandlerRoleResponse
  - `data` EnforcerV3InternalDomainRoleRole
    - `admin_managed` boolean
    - `created_at` string
    - `cross_tenant` boolean: Capability grants (additive; all false = baseline-only, like "user").
    - `description` string
    - `id` string
    - `mpp_ops` boolean: MPPOps: read-only MPP deposit-intent operator views (migration 000129).
    - `name` string
    - `slug` string
    - `tenant_manage` boolean
    - `tenant_read` boolean
    - `tenant_write` boolean
    - `updated_at` string
  - `success` boolean

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict
- `500`: Internal Server Error

---

[API](https://skmtc.dev/instruxi/apis/enforcer-api.md) · [All operations](https://skmtc.dev/instruxi/apis/enforcer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/instruxi/apis/enforcer-api/revisions/fa82bc1becc0?raw)