Organization roles
Use the REST API to interact with organization roles.
List organization fine-grained permissions for an organization
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.
- A user, or a user on a team, with the fine-grained permissions of
read_organization_custom_org_role
in the organization.
The authenticated user needs an access token with admin:org
scope or a fine-grained personal access token with the organization_custom_roles:read
permission to use this endpoint.
GitHub Apps must have the organization_custom_org_roles:read
organization permission to use this endpoint.
Parameters for "List organization fine-grained permissions for an organization"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
HTTP response status codes for "List organization fine-grained permissions for an organization"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "List organization fine-grained permissions for an organization"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-fine-grained-permissions
Response
Status: 200
[
{
"name": "read_organization_custom_org_role",
"description": "View organization roles"
},
{
"name": "write_organization_custom_org_role",
"description": "Manage custom organization roles"
}
]
Get all organization roles for an organization
Lists the organization roles available in this organization.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
read_organization_custom_org_role
in the organization.
The authenticated user needs an access token with admin:org
scope or a fine-grained personal access token with the organization_custom_roles:read
permission to use this endpoint.
GitHub Apps must have the organization_custom_org_roles:read
organization permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Get all organization roles for an organization"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
HTTP response status codes for "Get all organization roles for an organization"
Status code | Description |
---|---|
200 | Response - list of organization roles |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Get all organization roles for an organization"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles
Response - list of organization roles
Status: 200
{
"total_count": 2,
"roles": [
{
"id": 8030,
"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"
],
"organization": {
"login": "github",
"id": 9919,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
"avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/github",
"html_url": "https://github.com/github",
"followers_url": "https://api.github.com/users/github/followers",
"following_url": "https://api.github.com/users/github/following{/other_user}",
"gists_url": "https://api.github.com/users/github/gists{/gist_id}",
"starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/github/subscriptions",
"organizations_url": "https://api.github.com/users/github/orgs",
"repos_url": "https://api.github.com/users/github/repos",
"events_url": "https://api.github.com/users/github/events{/privacy}",
"received_events_url": "https://api.github.com/users/github/received_events",
"type": "Organization",
"site_admin": false
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
},
{
"id": 8031,
"name": "Auditor",
"description": "Permissions to read the organization audit log",
"permissions": [
"read_audit_logs"
],
"organization": {
"login": "github",
"id": 9919,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjk5MTk=",
"avatar_url": "https://avatars.githubusercontent.com/u/9919?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/github",
"html_url": "https://github.com/github",
"followers_url": "https://api.github.com/users/github/followers",
"following_url": "https://api.github.com/users/github/following{/other_user}",
"gists_url": "https://api.github.com/users/github/gists{/gist_id}",
"starred_url": "https://api.github.com/users/github/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/github/subscriptions",
"organizations_url": "https://api.github.com/users/github/orgs",
"repos_url": "https://api.github.com/users/github/repos",
"events_url": "https://api.github.com/users/github/events{/privacy}",
"received_events_url": "https://api.github.com/users/github/received_events",
"type": "Organization",
"site_admin": false
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
}
]
}
Create a custom organization role
Creates a custom organization role that can be assigned to users and teams, granting them specific permissions over the organization.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
write_organization_custom_org_role
in the organization.
The authenticated user needs an access token with admin:org
scope or a fine-grained personal access token with the organization_custom_roles:write
permission to use this endpoint.
GitHub Apps must have the organization_custom_org_roles:write
organization permission to use this endpoint.
For more information on custom organization roles, see "Managing people's access to your organization with roles."
Parameters for "Create a custom organization role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
Name, Type, Description |
---|
name string RequiredThe 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 RequiredA list of additional permissions included in this role. |
HTTP response status codes for "Create a custom organization role"
Status code | Description |
---|---|
201 | Created |
404 | Resource not found |
409 | Conflict |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Create a custom organization role"
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/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
Status: 201
{
"id": 8030,
"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"
],
"organization": {
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://api.github.com/orgs/github",
"repos_url": "https://api.github.com/orgs/github/repos",
"events_url": "https://api.github.com/orgs/github/events",
"hooks_url": "https://api.github.com/orgs/github/hooks",
"issues_url": "https://api.github.com/orgs/github/issues",
"members_url": "https://api.github.com/orgs/github/members{/member}",
"public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:19:11Z"
}
Remove all organization roles for a team
Removes all assigned organization roles from a team.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members:write
organization permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Remove all organization roles for a team"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
team_slug string RequiredThe slug of the team name. |
HTTP response status codes for "Remove all organization roles for a team"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Remove all organization roles for a team"
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/teams/TEAM_SLUG
Response
Status: 204
Assign an organization role to a team
Assigns an organization role to a team in an organization.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members
organization read-write permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Assign an organization role to a team"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
team_slug string RequiredThe slug of the team name. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Assign an organization role to a team"
Status code | Description |
---|---|
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 samples for "Assign an organization role to a team"
curl -L \
-X PUT \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/teams/TEAM_SLUG/ROLE_ID
Response
Status: 204
Remove an organization role from a team
Removes an organization role from a team.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members:write
organization permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Remove an organization role from a team"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
team_slug string RequiredThe slug of the team name. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Remove an organization role from a team"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Remove an organization role from a team"
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/teams/TEAM_SLUG/ROLE_ID
Response
Status: 204
Remove all organization roles for a user
Revokes all assigned organization roles from a user.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members:write
organization permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Remove all organization roles for a user"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
username string RequiredThe handle for the GitHub user account. |
HTTP response status codes for "Remove all organization roles for a user"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Remove all organization roles for a user"
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/users/USERNAME
Response
Status: 204
Assign an organization role to a user
Assigns an organization role to a member of an organization.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members
organization read-write permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Assign an organization role to a user"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
username string RequiredThe handle for the GitHub user account. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Assign an organization role to a user"
Status code | Description |
---|---|
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 samples for "Assign an organization role to a user"
curl -L \
-X PUT \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/users/USERNAME/ROLE_ID
Response
Status: 204
Remove an organization role from a user
Remove an organization role from a user.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members:write
organization permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Remove an organization role from a user"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
username string RequiredThe handle for the GitHub user account. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Remove an organization role from a user"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Remove an organization role from a user"
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/users/USERNAME/ROLE_ID
Response
Status: 204
Get an organization role
Gets an organization role that is available to this organization.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
read_organization_custom_org_role
in the organization.
The authenticated user needs an access token with admin:org
scope or a fine-grained personal access token with the organization_custom_roles:read
permission to use this endpoint.
GitHub Apps must have the organization_custom_org_roles:read
organization permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "Get an organization role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Get an organization role"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Get an organization role"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/ROLE_ID
Response
Status: 200
{
"id": 8030,
"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"
],
"organization": {
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://api.github.com/orgs/github",
"repos_url": "https://api.github.com/orgs/github/repos",
"events_url": "https://api.github.com/orgs/github/events",
"hooks_url": "https://api.github.com/orgs/github/hooks",
"issues_url": "https://api.github.com/orgs/github/issues",
"members_url": "https://api.github.com/orgs/github/members{/member}",
"public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z"
}
Update a custom organization role
Updates an existing custom organization role. Permission changes will apply to all assignees.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
write_organization_custom_org_role
in the organization.
The authenticated user needs an access token with admin:org
scope or a fine-grained personal access token with the organization_custom_roles:write
permission to use this endpoint.
GitHub Apps must have the organization_custom_org_roles:write
organization permission to use this endpoint.
For more information on custom organization roles, see "Managing people's access to your organization with roles."
Parameters for "Update a custom organization role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
Name, Type, Description |
---|
name string 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 A list of additional permissions included in this role. |
HTTP response status codes for "Update a custom organization role"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
409 | Conflict |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Update a custom organization role"
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/ROLE_ID \
-d '{"description":"Permissions to manage custom roles within an org."}'
Response
Status: 200
{
"id": 8030,
"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"
],
"organization": {
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://api.github.com/orgs/github",
"repos_url": "https://api.github.com/orgs/github/repos",
"events_url": "https://api.github.com/orgs/github/events",
"hooks_url": "https://api.github.com/orgs/github/hooks",
"issues_url": "https://api.github.com/orgs/github/issues",
"members_url": "https://api.github.com/orgs/github/members{/member}",
"public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:19:11Z"
}
Delete a custom organization role.
Deletes a custom organization role.
To use this endpoint, the authenticated user must be one of:
- An administrator for the organization.
- A user, or a user on a team, with the fine-grained permissions of
write_organization_custom_org_role
in the organization.
The authenticated user needs an access token with admin:org
scope or a fine-grained personal access token with the organization_custom_roles:write
permission to use this endpoint.
GitHub Apps must have the organization_custom_org_roles:write
organization permission to use this endpoint.
For more information on custom organization roles, see "Managing people's access to your organization with roles."
Parameters for "Delete a custom organization role."
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
HTTP response status codes for "Delete a custom organization role."
Status code | Description |
---|---|
204 | No Content |
Code samples for "Delete a custom organization role."
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/ROLE_ID
Response
Status: 204
List teams that are assigned to an organization role
Lists the teams that are assigned to an organization role.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members
organization read permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "List teams that are assigned to an organization role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
Name, Type, Description |
---|
per_page integer The number of results per page (max 100). Default: |
page integer Page number of the results to fetch. Default: |
HTTP response status codes for "List teams that are assigned to an organization role"
Status code | Description |
---|---|
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 samples for "List teams that are assigned to an organization role"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/ROLE_ID/teams
Response - List of assigned teams
Status: 200
[
{
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://github.com/orgs/github/teams/justice-league",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"notification_setting": "notifications_enabled",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos",
"parent": null
}
]
List users that are assigned to an organization role
Lists organization members that are assigned to an organization role.
To use this endpoint, you must be an administrator for the organization, and you must use an access token with the admin:org
scope.
GitHub Apps must have the members
organization read permission to use this endpoint.
For more information on organization roles, see "Managing people's access to your organization with roles."
Parameters for "List users that are assigned to an organization role"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
role_id integer RequiredThe unique identifier of the role. |
Name, Type, Description |
---|
per_page integer The number of results per page (max 100). Default: |
page integer Page number of the results to fetch. Default: |
HTTP response status codes for "List users that are assigned to an organization role"
Status code | Description |
---|---|
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 samples for "List users that are assigned to an organization role"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/organization-roles/ROLE_ID/users
Response - List of assigned users
Status: 200
[
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
}
]