REST API endpoints for enterprise roles - GitHub Enterprise Cloud Docs

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_role in the enterprise.

OAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.

Fine-grained access tokens for "Get all enterprise roles for an enterprise"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (read)

Parameters for "Get all enterprise roles for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

HTTP response status codes for "Get all enterprise roles for an enterprise"

Status code	Description
`200`	Response - list of enterprise roles
`403`	Forbidden
`404`	Resource not found

Code samples for "Get all enterprise roles for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/enterprise-roles

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

Response - 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_role in the enterprise.

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

Fine-grained access tokens for "Remove all enterprise roles from a team"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (write)

Parameters for "Remove all enterprise roles from a team"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`team_slug` string Required The slug of the enterprise team name.

HTTP response status codes for "Remove all enterprise roles from a team"

Status code	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.

Code samples for "Remove all enterprise roles from a team"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/enterprise-roles/teams/{team_slug}

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

Response

Status: 204

Assign 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_role in the enterprise.

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

Fine-grained access tokens for "Assign an enterprise role to a team"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (write)

Parameters for "Assign an enterprise role to a team"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`team_slug` string Required The slug of the enterprise team name.
`role_id` integer Required The unique identifier of the role.

HTTP response status codes for "Assign an enterprise role to a team"

Status code	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.

Code samples for "Assign an enterprise role to a team"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

put/enterprises/{enterprise}/enterprise-roles/teams/{team_slug}/{role_id}

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_ID

Response

Status: 204

Remove 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_role in the enterprise.

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

Fine-grained access tokens for "Remove an enterprise role from a team"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (write)

Parameters for "Remove an enterprise role from a team"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`team_slug` string Required The slug of the enterprise team name.
`role_id` integer Required The unique identifier of the role.

HTTP response status codes for "Remove an enterprise role from a team"

Status code	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.

Code samples for "Remove an enterprise role from a team"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/enterprise-roles/teams/{team_slug}/{role_id}

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_ID

Response

Status: 204

Remove 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_role in the enterprise.

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

Fine-grained access tokens for "Remove all enterprise roles from a user"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (write)

Parameters for "Remove all enterprise roles from a user"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`username` string Required The handle for the GitHub user account.

HTTP response status codes for "Remove all enterprise roles from a user"

Status code	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.

Code samples for "Remove all enterprise roles from a user"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/enterprise-roles/users/{username}

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

Response

Status: 204

Assign 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_role in the enterprise.

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

Fine-grained access tokens for "Assign an enterprise role to an enterprise user"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (write)

Parameters for "Assign an enterprise role to an enterprise user"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`username` string Required The handle for the GitHub user account.
`role_id` integer Required The unique identifier of the role.

HTTP response status codes for "Assign an enterprise role to an enterprise user"

Status code	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.

Code samples for "Assign an enterprise role to an enterprise user"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

put/enterprises/{enterprise}/enterprise-roles/users/{username}/{role_id}

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_ID

Response

Status: 204

Remove 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_role in the enterprise.

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

Fine-grained access tokens for "Remove enterprise user role assignment"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (write)

Parameters for "Remove enterprise user role assignment"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`username` string Required The handle for the GitHub user account.
`role_id` integer Required The unique identifier of the role.

HTTP response status codes for "Remove enterprise user role assignment"

Status code	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.

Code samples for "Remove enterprise user role assignment"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/enterprise-roles/users/{username}/{role_id}

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_ID

Response

Status: 204

Get 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_role in the enterprise.

OAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.

Fine-grained access tokens for "Get an enterprise role"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (read)

Parameters for "Get an enterprise role"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`role_id` integer Required The unique identifier of the role.

HTTP response status codes for "Get an enterprise role"

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples for "Get an enterprise role"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/enterprise-roles/{role_id}

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

Response

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_role in the enterprise.

OAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.

Fine-grained access tokens for "List teams that are assigned to an enterprise role"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (read)

Parameters for "List teams that are assigned to an enterprise role"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`role_id` integer Required The unique identifier of the role.

Query parameters
Name, Type, Description
`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 for "List teams that are assigned to an enterprise role"

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples for "List teams that are assigned to an enterprise role"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/enterprise-roles/{role_id}/teams

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/teams

Response

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_role in the enterprise.

OAuth app tokens and personal access tokens (classic) require the enterprise:admin scope to access this endpoint.

Fine-grained access tokens for "List users that are assigned to an enterprise role"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Custom enterprise roles" enterprise permissions (read)

Parameters for "List users that are assigned to an enterprise role"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`role_id` integer Required The unique identifier of the role.

Query parameters
Name, Type, Description
`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 for "List users that are assigned to an enterprise role"

Status code	Description
`200`	Response - List of assigned users
`403`	Forbidden
`404`	Resource not found

Code samples for "List users that are assigned to an enterprise role"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/enterprise-roles/{role_id}/users

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/users

Response - 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
  }
]