---
title: "Create role"
method: POST
path: "/zones/{zoneId}/roles"
tags: ["Zone Roles"]
---

# Create role

`POST /zones/{zoneId}/roles`

Creates a new customer-owned role in the specified zone. The owner_type is always customer; platform roles are managed by Keycard.

## Path parameters

- `zoneId` string, required

## Request body

- IamRoleCreate — Schema for creating a new role
  - `identifier` string, required — Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.
  - `description` string — Human-readable description

## Response `201`

A role that can be assigned to users within a zone.

- IamRole — A role that can be assigned to users within a zone.
  - `id` string, required — Unique identifier of the role
  - `zone_id` string, required — Zone this role belongs to
  - `identifier` string, required — Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.
  - `description` string, nullable — Human-readable description
  - `owner_type` 'platform' | 'customer', required — Who owns this role. Platform-owned roles are managed by Keycard and cannot be modified or deleted via the API; customer-owned roles are user-created.
  - `created_at` string, date-time, required — Entity creation timestamp
  - `updated_at` string, date-time, required — Entity update timestamp

## Other responses

- `400` — Error response
- `409` — Error response
- `default` — Error response

## Changes

- **2026-08-26** `d65d51379d93` — 1 breaking, 3 info
  - added the pattern `^[a-z0-9]+(?:[-_][a-z0-9]+)*$` to the request property `identifier`
  - added the non-success response with the status `400`
  - added the non-success response with the status `409`
  - the `identifier` response's property pattern `^[a-z0-9]+(?:[-_][a-z0-9]+)*$` was added for the status `201`
- **2026-06-09** `7e0e4fa2e16f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/keycardai/apis/untitled-api/changes/zones/:zoneId/roles/post.md)

---

[API](https://skmtc.dev/keycardai/apis/untitled-api.md) · [All operations](https://skmtc.dev/keycardai/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/keycardai/untitled-api/revisions/d65d51379d93/schema)