---
title: "Create a custom organization role"
method: POST
path: "/orgs/{org}/organization-roles"
tags: ["orgs"]
---

# Create a custom organization role

`POST /orgs/{org}/organization-roles`

Creates a custom organization role that can be assigned to users and teams, granting them specific
permissions over the organization and optionally across all repositories in the organization. For
more information on custom organization roles, see "[Managing people's access to your organization with roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles)."

To include repository permissions in an organization role, you must also include the `base_role`
field, which is one of `read`, `write`, `triage`, `maintain`, or `admin` (or `none` if no base role is set). This base role provides a set of
fine-grained permissions as well as implicit permissions - those that aren't exposed as fine-grained permissions
and can only be granted through the base role (like "reading a repo").  If you include repository permissions, those
permissions apply across all of the repositories in the organization. You do not have to include organization permissions
in order to add repository permissions.

See "[List repository permissions](https://docs.github.com/enterprise-cloud@latest/rest/orgs/custom-roles#list-repository-fine-grained-permissions-for-an-organization)" for valid repository permissions.

To use this endpoint, the authenticated user must be one of:

- An administrator for the organization.
- An organization member (or a member of a team) assigned a custom organization role that includes the **Manage custom organization roles** (`write_organization_custom_org_role`) permission. For more information, see "[Permissions for organization access](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles#permissions-for-organization-access)."

OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.

## Path parameters

- `org` string, required

## Request body

- OrganizationCustomOrganizationRoleCreateSchema
  - `name` string, required — The name of the custom role.
  - `description` string — A short description about the intended usage of this role or what permissions it grants.
  - `permissions` string[], required — A list of additional permissions included in this role.
  - `base_role` 'read' | 'triage' | 'write' | 'maintain' | 'admin' — The system role from which this role can inherit permissions.

## Response `201`

Response

- OrganizationRole — Organization roles
  - `id` integer, required — The unique identifier of the role.
  - `name` string, required — The name of the role.
  - `description` string, nullable — A short description about who this role is for or what permissions it grants.
  - `base_role` 'read' | 'triage' | 'write' | 'maintain' | 'admin', nullable — The system role from which this role inherits permissions.
  - `source` 'Organization' | 'Enterprise' | 'Predefined', nullable — Source answers the question, "where did this role come from?"
  - `permissions` string[], required — A list of permissions included in this role.
  - `organization` NullableSimpleUser, nullable, required — A GitHub user.
    - `name` string, nullable
    - `email` string, nullable
    - `login` string, required
    - `id` integer, required
    - `node_id` string, required
    - `avatar_url` string, uri, required
    - `gravatar_id` string, nullable, required
    - `url` string, uri, required
    - `html_url` string, uri, required
    - `followers_url` string, uri, required
    - `following_url` string, required
    - `gists_url` string, required
    - `starred_url` string, required
    - `subscriptions_url` string, uri, required
    - `organizations_url` string, uri, required
    - `repos_url` string, uri, required
    - `events_url` string, required
    - `received_events_url` string, uri, required
    - `type` string, required
    - `site_admin` boolean, required
    - `starred_at` string
    - `user_view_type` string
  - `created_at` string, date-time, required — The date and time the role was created.
  - `updated_at` string, date-time, required — The date and time the role was last updated.

## Other responses

- `404` — Resource not found
- `409` — Conflict
- `422` — Validation failed, or the endpoint has been spammed.

---

[API](https://skmtc.net/github/apis/github-v3-rest-api-2.md) · [All operations](https://skmtc.net/github/apis/github-v3-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/github/github-v3-rest-api-2/versions/8ae6d0c8716e/schema)