# REST API endpoints for organization roles

Use the REST API to interact with organization roles.

> [!NOTE]
> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.

## List organization fine-grained permissions for an organization

```
GET /orgs/{org}/organization-fine-grained-permissions
```

Lists the fine-grained permissions that can be used in custom organization roles for an organization. For more information, see "Managing people's access to your organization with roles."
To list the fine-grained permissions that can be used in custom repository roles for an organization, see "List repository fine-grained permissions for an organization."
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 View organization roles (read_organization_custom_org_role) permission. For more information, see "Permissions for organization access."

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

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

### HTTP response status codes

- **200** - OK

- **404** - Resource not found

- **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-fine-grained-permissions
```

**Response schema (Status: 200):**

Array of `Organization Fine-Grained Permission`:
  * `name`: required, string
  * `description`: required, string

## Get all organization roles for an organization

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

Lists the organization roles available in this organization. For more information on organization roles, see "Using organization roles."
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 View organization roles (read_organization_custom_org_role) permission. For more information, see "Permissions for organization access."

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

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

### HTTP response status codes

- **200** - Response - list of organization roles

- **404** - Resource not found

- **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles
```

**Response schema (Status: 200):**

* `total_count`: integer
* `roles`: array of `Organization Role`:
  * `id`: required, integer, format: int64
  * `name`: required, string
  * `description`: string or null
  * `base_role`: string or null, enum: `read`, `triage`, `write`, `maintain`, `admin`, `null`
  * `source`: string or null, enum: `Organization`, `Enterprise`, `Predefined`, `null`
  * `permissions`: required, array of string
  * `organization`: required, any of:
    * **null**
    * **Simple User**
      * `name`: string or null
      * `email`: string or null
      * `login`: required, string
      * `id`: required, integer, format: int64
      * `node_id`: required, string
      * `avatar_url`: required, string, format: uri
      * `gravatar_id`: required, string or null
      * `url`: required, string, format: uri
      * `html_url`: required, string, format: uri
      * `followers_url`: required, string, format: uri
      * `following_url`: required, string
      * `gists_url`: required, string
      * `starred_url`: required, string
      * `subscriptions_url`: required, string, format: uri
      * `organizations_url`: required, string, format: uri
      * `repos_url`: required, string, format: uri
      * `events_url`: required, string
      * `received_events_url`: required, string, format: uri
      * `type`: required, string
      * `site_admin`: required, boolean
      * `starred_at`: string
      * `user_view_type`: string
  * `created_at`: required, string, format: date-time
  * `updated_at`: required, string, format: date-time

## 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."
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" 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."

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

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

#### Body parameters

- **`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`** (array of strings) (required)
  A list of additional permissions included in this role.

- **`base_role`** (string)
  The system role from which this role can inherit permissions.
  Can be one of: `read`, `triage`, `write`, `maintain`, `admin`

### HTTP response status codes

- **201** - Created

- **404** - Resource not found

- **409** - Conflict

- **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles \
  -d '{
  "name": "Custom Role Manager",
  "description": "Permissions to manage custom roles within an org",
  "permissions": [
    "write_organization_custom_repo_role",
    "write_organization_custom_org_role",
    "read_organization_custom_repo_role",
    "read_organization_custom_org_role"
  ]
}'
```

**Response schema (Status: 201):**

* `id`: required, integer, format: int64
* `name`: required, string
* `description`: string or null
* `base_role`: string or null, enum: `read`, `triage`, `write`, `maintain`, `admin`, `null`
* `source`: string or null, enum: `Organization`, `Enterprise`, `Predefined`, `null`
* `permissions`: required, array of string
* `organization`: required, any of:
  * **null**
  * **Simple User**
    * `name`: string or null
    * `email`: string or null
    * `login`: required, string
    * `id`: required, integer, format: int64
    * `node_id`: required, string
    * `avatar_url`: required, string, format: uri
    * `gravatar_id`: required, string or null
    * `url`: required, string, format: uri
    * `html_url`: required, string, format: uri
    * `followers_url`: required, string, format: uri
    * `following_url`: required, string
    * `gists_url`: required, string
    * `starred_url`: required, string
    * `subscriptions_url`: required, string, format: uri
    * `organizations_url`: required, string, format: uri
    * `repos_url`: required, string, format: uri
    * `events_url`: required, string
    * `received_events_url`: required, string, format: uri
    * `type`: required, string
    * `site_admin`: required, boolean
    * `starred_at`: string
    * `user_view_type`: string
* `created_at`: required, string, format: date-time
* `updated_at`: required, string, format: date-time

## Remove all organization roles for a team

```
DELETE /orgs/{org}/organization-roles/teams/{team_slug}
```

Removes all assigned organization roles from a team. For more information on organization roles, see "Using organization roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`team_slug`** (string) (required)
  The slug of the team name.

### HTTP response status codes

- **204** - No Content

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/teams/TEAM_SLUG
```

**Response schema (Status: 204):**

## Assign an organization role to a team

```
PUT /orgs/{org}/organization-roles/teams/{team_slug}/{role_id}
```

Assigns an organization role to a team in an organization. For more information on organization roles, see "Using organization roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`team_slug`** (string) (required)
  The slug of the team name.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

### HTTP response status codes

- **204** - No Content

- **404** - Response if the organization, team or role does not exist.

- **422** - Response if the organization roles feature is not enabled for the organization, or validation failed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X PUT \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/teams/TEAM_SLUG/ROLE_ID
```

**Response schema (Status: 204):**

## Remove an organization role from a team

```
DELETE /orgs/{org}/organization-roles/teams/{team_slug}/{role_id}
```

Removes an organization role from a team. For more information on organization roles, see "Using organization roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`team_slug`** (string) (required)
  The slug of the team name.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

### HTTP response status codes

- **204** - No Content

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/teams/TEAM_SLUG/ROLE_ID
```

**Response schema (Status: 204):**

## Remove all organization roles for a user

```
DELETE /orgs/{org}/organization-roles/users/{username}
```

Revokes all assigned organization roles from a user. For more information on organization roles, see "Using organization roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`username`** (string) (required)
  The handle for the GitHub user account.

### HTTP response status codes

- **204** - No Content

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/users/USERNAME
```

**Response schema (Status: 204):**

## Assign an organization role to a user

```
PUT /orgs/{org}/organization-roles/users/{username}/{role_id}
```

Assigns an organization role to a member of an organization. For more information on organization roles, see "Using organization roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`username`** (string) (required)
  The handle for the GitHub user account.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

### HTTP response status codes

- **204** - No Content

- **404** - Response if the organization, user or role does not exist.

- **422** - Response if the organization roles feature is not enabled enabled for the organization, the validation failed, or the user is not an organization member.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X PUT \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/users/USERNAME/ROLE_ID
```

**Response schema (Status: 204):**

## Remove an organization role from a user

```
DELETE /orgs/{org}/organization-roles/users/{username}/{role_id}
```

Remove an organization role from a user. For more information on organization roles, see "Using organization roles."
The authenticated user must be an administrator for the organization to use this endpoint.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`username`** (string) (required)
  The handle for the GitHub user account.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

### HTTP response status codes

- **204** - No Content

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/users/USERNAME/ROLE_ID
```

**Response schema (Status: 204):**

## Get an organization role

```
GET /orgs/{org}/organization-roles/{role_id}
```

Gets an organization role that is available to this organization. For more information on organization roles, see "Using organization roles."
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 View organization roles (read_organization_custom_org_role) permission. For more information, see "Permissions for organization access."

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

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

### HTTP response status codes

- **200** - OK

- **404** - Resource not found

- **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/ROLE_ID
```

**Response schema (Status: 200):**

Same response schema as [Create a custom organization role](#create-a-custom-organization-role).

## Update a custom organization role

```
PATCH /orgs/{org}/organization-roles/{role_id}
```

Updates an existing custom organization role. Permission changes will apply to all assignees. For more information on custom organization roles, see "Managing people's access to your organization with roles."
If the update would add repository permissions, the base_role must also be set to a value besides none, either
previously or as part of the update.
If the update sets the base_role field to none, you must also remove all of the repository
permissions as well, otherwise the update will fail.
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."

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

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

#### Body parameters

- **`name`** (string)
  The name of the custom role.

- **`description`** (string)
  A short description about the intended use of this role or the permissions it grants.

- **`permissions`** (array of strings)
  A list of additional permissions included in this role.

- **`base_role`** (string)
  The system role from which this role can inherit permissions.
  Can be one of: `none`, `read`, `triage`, `write`, `maintain`, `admin`

### HTTP response status codes

- **200** - OK

- **404** - Resource not found

- **409** - Conflict

- **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X PATCH \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/ROLE_ID \
  -d '{
  "description": "Permissions to manage custom roles within an org."
}'
```

**Response schema (Status: 200):**

Same response schema as [Create a custom organization role](#create-a-custom-organization-role).

## Delete a custom organization role.

```
DELETE /orgs/{org}/organization-roles/{role_id}
```

Deletes a custom organization role. For more information on custom organization roles, see "Managing people's access to your organization with roles."
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."

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

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

### HTTP response status codes

- **204** - No Content

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/ROLE_ID
```

**Response schema (Status: 204):**

## List teams that are assigned to an organization role

```
GET /orgs/{org}/organization-roles/{role_id}/teams
```

Lists the teams that are assigned to an organization role. For more information on organization roles, see "Using organization roles."
To use this endpoint, you must be an administrator for the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

- **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

- **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

- **200** - Response - List of assigned teams

- **404** - Response if the organization or role does not exist.

- **422** - Response if the organization roles feature is not enabled or validation failed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/ROLE_ID/teams
```

**Response schema (Status: 200):**

Array of `A Role Assignment for a Team`:
  * `assignment`: string, enum: `direct`, `indirect`, `mixed`
  * `id`: required, integer
  * `node_id`: required, string
  * `name`: required, string
  * `slug`: required, string
  * `description`: required, string or null
  * `privacy`: string
  * `notification_setting`: string
  * `permission`: required, string
  * `permissions`: object:
    * `pull`: required, boolean
    * `triage`: required, boolean
    * `push`: required, boolean
    * `maintain`: required, boolean
    * `admin`: required, boolean
  * `url`: required, string, format: uri
  * `html_url`: required, string, format: uri
  * `members_url`: required, string
  * `repositories_url`: required, string, format: uri
  * `parent`: required, any of:
    * **null**
    * **Team Simple**
      * `id`: required, integer
      * `node_id`: required, string
      * `url`: required, string, format: uri
      * `members_url`: required, string
      * `name`: required, string
      * `description`: required, string or null
      * `permission`: required, string
      * `privacy`: string
      * `notification_setting`: string
      * `html_url`: required, string, format: uri
      * `repositories_url`: required, string, format: uri
      * `slug`: required, string
      * `ldap_dn`: string
      * `type`: required, string, enum: `enterprise`, `organization`
      * `organization_id`: integer
      * `enterprise_id`: integer
  * `type`: required, string, enum: `enterprise`, `organization`
  * `organization_id`: integer
  * `enterprise_id`: integer

## List users that are assigned to an organization role

```
GET /orgs/{org}/organization-roles/{role_id}/users
```

Lists organization members that are assigned to an organization role. For more information on organization roles, see "Using organization roles."
To use this endpoint, you must be an administrator for the organization.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`org`** (string) (required)
  The organization name. The name is not case sensitive.

- **`role_id`** (integer) (required)
  The unique identifier of the role.

- **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

- **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

- **200** - Response - List of assigned users

- **404** - Response if the organization or role does not exist.

- **422** - Response if the organization roles feature is not enabled or validation failed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/orgs/ORG/organization-roles/ROLE_ID/users
```

**Response schema (Status: 200):**

Array of `A Role Assignment for a User`:
  * `assignment`: string, enum: `direct`, `indirect`, `mixed`
  * `inherited_from`: array of `Team Simple`:
    * `id`: required, integer
    * `node_id`: required, string
    * `url`: required, string, format: uri
    * `members_url`: required, string
    * `name`: required, string
    * `description`: required, string or null
    * `permission`: required, string
    * `privacy`: string
    * `notification_setting`: string
    * `html_url`: required, string, format: uri
    * `repositories_url`: required, string, format: uri
    * `slug`: required, string
    * `ldap_dn`: string
    * `type`: required, string, enum: `enterprise`, `organization`
    * `organization_id`: integer
    * `enterprise_id`: integer
  * `name`: string or null
  * `email`: string or null
  * `login`: required, string
  * `id`: required, integer
  * `node_id`: required, string
  * `avatar_url`: required, string, format: uri
  * `gravatar_id`: required, string or null
  * `url`: required, string, format: uri
  * `html_url`: required, string, format: uri
  * `followers_url`: required, string, format: uri
  * `following_url`: required, string
  * `gists_url`: required, string
  * `starred_url`: required, string
  * `subscriptions_url`: required, string, format: uri
  * `organizations_url`: required, string, format: uri
  * `repos_url`: required, string, format: uri
  * `events_url`: required, string
  * `received_events_url`: required, string, format: uri
  * `type`: required, string
  * `site_admin`: required, boolean
  * `starred_at`: string
  * `user_view_type`: string