---
title: "Create a system template and copy it into every company"
method: POST
path: "/api/roles/templates"
tags: ["Permissions"]
---

# Create a system template and copy it into every company

`POST /api/roles/templates`

Create a MODEL (`idcompany IS NULL`, `template_key` set) and fan it out.

This is what `create_role`'s docstring used to say could not be done, and
both of its reasons are answered rather than waived:

* *"a template minted from a dialog has an empty `Z_RolePermissions`"* —
  `modules` is required and non-empty, validated against `MODULE_KEYS`, and
  written in the same transaction as the template row.
* *"the console cannot re-create templates"*, i.e. a mistake is
  unrepairable — `DELETE /roles/{id}?delete_template=true` now removes a
  console-created model together with its whole family, atomically, while
  nobody holds it.

The response names every company that did NOT get a copy and why. `skipped`
is not an error path: a tenant that already owns a role with this name
cannot have the copy (`UX_Z_Roles_company_name`), and refusing the whole
template over one tenant's naming choice would make the feature unusable
for exactly the generic names it is for. Retry that company with
`POST /roles/{id}/copies` once the collision is resolved.

## Headers

- `x-api-token` string, nullable

## Request body

- SystemTemplateCreate — A new system TEMPLATE — the row every company gets a copy of. Separate from `RoleCreate` on purpose. `POST /roles` creates a role INSIDE a company and `test_platform_role_catalogue.py` pins its field set; folding a scope switch into it would make the safest, most-used shape carry the dangerous one's defaults.
  - `name` string, required
  - `template_key` string, required
  - `description` string, nullable
  - `modules` string[], required
  - `create_system_template` boolean

## Response `201`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-02** `8492136eefc5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/multigest/apis/multigest-protected-api/changes/api/roles/templates/post.md)

---

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