---
title: "Validate a role document"
method: POST
path: "/api/v1/roles/validate"
tags: ["roles"]
---

# Validate a role document

`POST /api/v1/roles/validate`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in header `Authorization`

Checks a role document, in JSON or YAML, without saving it, and lists every problem found with where it is, so an editor can mark each one. Pass id to check an edit to an existing role, so it keeping its own name is not reported as a clash.

## Query parameters

- `id` string

## Request body

- V1RolesCreateRoleRequest
  - `description` string
  - `name` string
  - `permission_ids` string[]
  - `permission_keys` string[]: PermissionKeys names permissions as resource_type:action keys, the form a hand-written role document uses.

## Response `200`

OK

- ValidateRoleResponse
  - `problems` RoleDocumentProblem[]
    - `message` string
    - `path` string
  - `valid` boolean

## Other responses

- `400`: Bad Request

## Changes

> 65 revisions in range; 1 not diffed.

- **2026-10-23** `18c57b576cb6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/marmotdata/apis/marmot-api/changes/api/v1/roles/validate/post.md)

---

[API](https://skmtc.dev/marmotdata/apis/marmot-api.md) - [All operations](https://skmtc.dev/marmotdata/apis/marmot-api/llms.txt) - [OpenAPI document](https://skmtc.dev/marmotdata/apis/marmot-api/revisions/18c57b576cb6?raw)