REST API endpoints for enterprise roles
Use the REST API to manage the enterprise roles available in this enterprise
Get all enterprise roles for an enterprise
Lists the enterprise roles available in this enterprise.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
read_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.
Jetons d’accès affinés pour « Get all enterprise roles for an enterprise »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (read)
Paramètres pour « Get all enterprise roles for an enterprise »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
Codes d’état de la réponse HTTP pour « Get all enterprise roles for an enterprise »
| Code d’état | Description |
|---|---|
200 | Response - list of enterprise roles |
403 | Forbidden |
404 | Resource not found |
Exemples de code pour « Get all enterprise roles for an enterprise »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-rolesResponse - list of enterprise roles
Status: 200{
"total_count": 2,
"roles": [
{
"id": 8030,
"name": "Security Manager",
"description": "A role for security managers",
"permissions": [
"read_enterprise_custom_enterprise_role",
"write_enterprise_security_configuration"
],
"enterprise": {
"id": "1,",
"slug": "github-inc",
"name": "GitHub, Inc",
"node_id": "E_kgAB",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great enterprise",
"website_url": null,
"html_url": "https://github.com/enterprises/github-inc",
"created_at": "2025-07-17T18:00:58Z",
"updated_at": "2025-07-17T18:00:58Z"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z",
"source": "Enterprise"
},
{
"id": 8031,
"name": "Enterprise Auditor",
"description": "Permissions to read enterprise audit logs and security settings",
"permissions": [
"read_enterprise_audit_logs",
"read_enterprise_security_configuration"
],
"enterprise": {
"id": "1,",
"slug": "github-inc",
"name": "GitHub, Inc",
"node_id": "E_kgAB",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great enterprise",
"website_url": null,
"html_url": "https://github.com/enterprises/github-inc",
"created_at": "2025-07-17T18:00:58Z",
"updated_at": "2025-07-17T18:00:58Z"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z",
"source": "Enterprise"
}
]
}Remove all enterprise roles from a team
Removes all assigned enterprise roles from a team in an enterprise.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
write_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
Jetons d’accès affinés pour « Remove all enterprise roles from a team »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (write)
Paramètres pour « Remove all enterprise roles from a team »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
team_slug string ObligatoireThe slug of the enterprise team name. |
Codes d’état de la réponse HTTP pour « Remove all enterprise roles from a team »
| Code d’état | Description |
|---|---|
204 | No Content |
403 | Forbidden |
404 | Resource not found |
422 | Response if the enterprise roles feature is not enabled for the enterprise, or validation failed. |
Exemples de code pour « Remove all enterprise roles from a team »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/teams/TEAM_SLUGResponse
Status: 204Assign an enterprise role to a team
Assigns an enterprise role to a team in an enterprise.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
write_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
Jetons d’accès affinés pour « Assign an enterprise role to a team »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (write)
Paramètres pour « Assign an enterprise role to a team »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
team_slug string ObligatoireThe slug of the enterprise team name. |
role_id integer ObligatoireThe unique identifier of the role. |
Codes d’état de la réponse HTTP pour « Assign an enterprise role to a team »
| Code d’état | Description |
|---|---|
204 | No Content |
403 | Forbidden |
404 | Resource not found |
422 | Response if the enterprise roles feature is not enabled for the enterprise, or validation failed. |
Exemples de code pour « Assign an enterprise role to a team »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/teams/TEAM_SLUG/ROLE_IDResponse
Status: 204Remove an enterprise role from a team
Removes an enterprise role from a team in an enterprise.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
write_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
Jetons d’accès affinés pour « Remove an enterprise role from a team »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (write)
Paramètres pour « Remove an enterprise role from a team »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
team_slug string ObligatoireThe slug of the enterprise team name. |
role_id integer ObligatoireThe unique identifier of the role. |
Codes d’état de la réponse HTTP pour « Remove an enterprise role from a team »
| Code d’état | Description |
|---|---|
204 | No Content |
403 | Forbidden |
404 | Resource not found |
422 | Response if the enterprise roles feature is not enabled for the enterprise, or validation failed. |
Exemples de code pour « Remove an enterprise role from a team »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/teams/TEAM_SLUG/ROLE_IDResponse
Status: 204Remove all enterprise roles from a user
Removes all enterprise roles from an enterprise user in an enterprise.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
write_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
Jetons d’accès affinés pour « Remove all enterprise roles from a user »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (write)
Paramètres pour « Remove all enterprise roles from a user »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
username string ObligatoireThe handle for the GitHub user account. |
Codes d’état de la réponse HTTP pour « Remove all enterprise roles from a user »
| Code d’état | Description |
|---|---|
204 | No Content |
403 | Forbidden |
404 | Resource not found |
422 | Response if the enterprise roles feature is not enabled for the enterprise, or validation failed. |
Exemples de code pour « Remove all enterprise roles from a user »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/users/USERNAMEResponse
Status: 204Assign an enterprise role to an enterprise user
Assigns an enterprise role to a user in an enterprise.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
write_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
Jetons d’accès affinés pour « Assign an enterprise role to an enterprise user »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (write)
Paramètres pour « Assign an enterprise role to an enterprise user »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
username string ObligatoireThe handle for the GitHub user account. |
role_id integer ObligatoireThe unique identifier of the role. |
Codes d’état de la réponse HTTP pour « Assign an enterprise role to an enterprise user »
| Code d’état | Description |
|---|---|
204 | No Content |
403 | Forbidden |
404 | Resource not found |
422 | Response if the enterprise roles feature is not enabled for the enterprise, or validation failed. |
Exemples de code pour « Assign an enterprise role to an enterprise user »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/users/USERNAME/ROLE_IDResponse
Status: 204Remove enterprise user role assignment
Removes an enterprise role from an enterprise user.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
write_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
Jetons d’accès affinés pour « Remove enterprise user role assignment »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (write)
Paramètres pour « Remove enterprise user role assignment »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
username string ObligatoireThe handle for the GitHub user account. |
role_id integer ObligatoireThe unique identifier of the role. |
Codes d’état de la réponse HTTP pour « Remove enterprise user role assignment »
| Code d’état | Description |
|---|---|
204 | No Content |
403 | Forbidden |
404 | Resource not found |
422 | Response if the enterprise roles feature is not enabled for the enterprise, or validation failed. |
Exemples de code pour « Remove enterprise user role assignment »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/users/USERNAME/ROLE_IDResponse
Status: 204Get an enterprise role
Gets a custom enterprise role that is available within the enterprise.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
read_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.
Jetons d’accès affinés pour « Get an enterprise role »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (read)
Paramètres pour « Get an enterprise role »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
role_id integer ObligatoireThe unique identifier of the role. |
Codes d’état de la réponse HTTP pour « Get an enterprise role »
| Code d’état | Description |
|---|---|
200 | OK |
403 | Forbidden |
404 | Resource not found |
Exemples de code pour « Get an enterprise role »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/ROLE_IDResponse
Status: 200{
"id": 8030,
"name": "Security Manager",
"description": "A role for security managers",
"permissions": [
"read_enterprise_custom_enterprise_role",
"write_enterprise_security_configuration"
],
"enterprise": {
"id": "1,",
"slug": "github-inc",
"name": "GitHub, Inc",
"node_id": "E_kgAB",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great enterprise",
"website_url": null,
"html_url": "https://github.com/enterprises/github-inc",
"created_at": "2025-07-17T18:00:58Z",
"updated_at": "2025-07-17T18:00:58Z"
},
"created_at": "2022-07-04T22:19:11Z",
"updated_at": "2022-07-04T22:20:11Z",
"source": "Enterprise"
}List teams that are assigned to an enterprise role
Lists the teams that are assigned to an enterprise role.
To use this endpoint, the authenticated user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
read_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.
Jetons d’accès affinés pour « List teams that are assigned to an enterprise role »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (read)
Paramètres pour « List teams that are assigned to an enterprise role »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
role_id integer ObligatoireThe unique identifier of the role. |
| Nom, Type, Description |
|---|
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
Codes d’état de la réponse HTTP pour « List teams that are assigned to an enterprise role »
| Code d’état | Description |
|---|---|
200 | OK |
403 | Forbidden |
404 | Resource not found |
Exemples de code pour « List teams that are assigned to an enterprise role »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/ROLE_ID/teamsResponse
Status: 200[
{
"id": 1,
"name": "Justice League",
"description": "A great team.",
"slug": "justice-league",
"url": "https://api.github.com/enterprises/dc/teams/justice-league",
"group_id": "62ab9291-fae2-468e-974b-7e45096d5021",
"html_url": "https://github.com/enterprises/dc/teams/justice-league",
"members_url": "https://api.github.com/enterprises/dc/teams/justice-league/members{/member}",
"created_at": "2019-01-26T19:01:12Z",
"updated_at": "2019-01-26T19:14:43Z"
}
]List users that are assigned to an enterprise role
Lists enterprise members that are assigned to an enterprise role.
To use this endpoint, a user must be one of:
- An administrator for the enterprise.
- A user, or a user on a team, with the fine-grained permission
read_enterprise_custom_enterprise_rolein the enterprise.
OAuth app tokens and personal access tokens (classic) require the enterprise:admin scope to access this endpoint.
Jetons d’accès affinés pour « List users that are assigned to an enterprise role »
Ce point de terminaison fonctionne avec les types de jetons précis suivants:
Le jeton précis doit avoir l’ensemble d’autorisations suivant:
- "Custom enterprise roles" enterprise permissions (read)
Paramètres pour « List users that are assigned to an enterprise role »
| Nom, Type, Description |
|---|
accept string Setting to |
| Nom, Type, Description |
|---|
enterprise string ObligatoireThe slug version of the enterprise name. |
role_id integer ObligatoireThe unique identifier of the role. |
| Nom, Type, Description |
|---|
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
Codes d’état de la réponse HTTP pour « List users that are assigned to an enterprise role »
| Code d’état | Description |
|---|---|
200 | Response - List of assigned users |
403 | Forbidden |
404 | Resource not found |
Exemples de code pour « List users that are assigned to an enterprise role »
Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.
Exemple de requête
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/enterprises/ENTERPRISE/enterprise-roles/ROLE_ID/usersResponse - List of assigned users
Status: 200[
{
"assignment": "direct",
"inherited_from": [],
"name": "The Octocat",
"email": "octocat@github.com",
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "41d064eb2195891e12d0413f63227ea7",
"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
},
{
"assignment": "indirect",
"inherited_from": [
{
"id": 1,
"name": "Justice League",
"description": "Enterprise team for superheroes",
"slug": "justice-league",
"url": "https://api.github.com/enterprises/dc/teams/justice-league",
"sync_to_organizations": "disabled",
"organization_selection_type": "disabled",
"group_id": "62ab9291-fae2-468e-974b-7e45096d5021",
"group_name": "Justice League",
"html_url": "https://github.com/enterprises/dc/teams/justice-league",
"members_url": "https://api.github.com/enterprises/dc/teams/justice-league/members{/member}",
"created_at": "2019-01-26T19:01:12Z",
"updated_at": "2019-01-26T19:14:43Z"
}
],
"name": "Mona Lisa",
"email": "mona@github.com",
"login": "monalisa",
"id": 2,
"node_id": "MDQ6VXNlcjI=",
"avatar_url": "https://github.com/images/error/monalisa_happy.gif",
"gravatar_id": null,
"url": "https://api.github.com/users/monalisa",
"html_url": "https://github.com/monalisa",
"followers_url": "https://api.github.com/users/monalisa/followers",
"following_url": "https://api.github.com/users/monalisa/following{/other_user}",
"gists_url": "https://api.github.com/users/monalisa/gists{/gist_id}",
"starred_url": "https://api.github.com/users/monalisa/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/monalisa/subscriptions",
"organizations_url": "https://api.github.com/users/monalisa/orgs",
"repos_url": "https://api.github.com/users/monalisa/repos",
"events_url": "https://api.github.com/users/monalisa/events{/privacy}",
"received_events_url": "https://api.github.com/users/monalisa/received_events",
"type": "User",
"site_admin": false
}
]