---
search:
  tags:
    - Roles and permissions
    - POST
seo:
  description: >-
    Requires ac:create; granting organization:delete also requires… Reference
    for the POST /organizations/{organizationId}/roles endpoint in the Auth API.
sidebar:
  label: Create a custom Role
  badge: POST
title: Create a custom Role
type: openapi-operation
---
Requires ac:create; granting organization:delete also requires organization:delete. Built-in names are reserved, names are unique within the organization (409), and every resource a Grant selects must belong to the organization (400).

`POST /organizations/{organizationId}/roles`

**Request body** (`application/json`, required)

- `name` (string, required) — Trimmed and lower-cased; 1 to 64 characters, not a built-in name.
- `grants` (grant_document, required) — A Role's Grants as scoped statements. Statements add together. Responses are canonical, one statement per scope instance.

Request body example:

```json
{
  "name": "string",
  "grants": {
    "version": 1,
    "statements": [
      {
        "scope": {
          "type": "organization",
          "ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "all": true
        },
        "permissions": [
          "string"
        ]
      }
    ]
  }
}
```

**Responses**

- `201` — The created Role.
- `default` — The request failed.

Response example, 201:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "builtin": true,
  "grants": {
    "version": 1,
    "statements": [
      {
        "scope": {
          "type": "organization",
          "ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "all": true
        },
        "permissions": [
          "string"
        ]
      }
    ]
  },
  "created_at": "2019-08-24T14:15:22Z"
}
```
