{"meta":{"title":"企业角色的 REST API 终结点","intro":"使用 REST API 管理此企业中可用的企业角色","product":"REST API","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/rest","title":"REST API"},{"href":"/zh/enterprise-cloud@latest/rest/enterprise-admin","title":"企业管理"},{"href":"/zh/enterprise-cloud@latest/rest/enterprise-admin/enterprise-roles","title":"企业角色"}],"documentType":"article"},"body":"# 企业角色的 REST API 终结点\n\n使用 REST API 管理此企业中可用的企业角色\n\n> [!NOTE]\n> 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.\n\n## Get all enterprise roles for an enterprise\n\n```\nGET /enterprises/{enterprise}/enterprise-roles\n```\n\nLists the enterprise roles available in this enterprise.\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission read_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n### HTTP response status codes\n\n- **200** - Response - list of enterprise roles\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles\n```\n\n**Response schema (Status: 200):**\n\n* `total_count`: integer\n* `roles`: array of `Enterprise Role`:\n  * `id`: required, integer, format: int64\n  * `name`: required, string\n  * `description`: string or null\n  * `source`: string or null, enum: `Enterprise`, `Predefined`, `null`\n  * `permissions`: required, array of string\n  * `enterprise`: required, any of:\n    * **null**\n    * **Enterprise**\n      * `description`: string or null\n      * `html_url`: required, string, format: uri\n      * `website_url`: string or null, format: uri\n      * `id`: required, integer\n      * `node_id`: required, string\n      * `name`: required, string\n      * `slug`: required, string\n      * `created_at`: required, string or null, format: date-time\n      * `updated_at`: required, string or null, format: date-time\n      * `avatar_url`: required, string, format: uri\n  * `created_at`: required, string, format: date-time\n  * `updated_at`: required, string, format: date-time\n\n## Remove all enterprise roles from a team\n\n```\nDELETE /enterprises/{enterprise}/enterprise-roles/teams/{team_slug}\n```\n\nRemoves all assigned enterprise roles from a team in an enterprise.\nWarning\n\nThis API is not available for Copilot Business for non-GHE.\n\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission write_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`team_slug`** (string) (required)\n  The slug of the enterprise team name.\n\n### HTTP response status codes\n\n- **204** - No Content\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **422** - Response if the enterprise roles feature is not enabled for the enterprise, or validation failed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X DELETE \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/teams/TEAM_SLUG\n```\n\n**Response schema (Status: 204):**\n\n## Assign an enterprise role to a team\n\n```\nPUT /enterprises/{enterprise}/enterprise-roles/teams/{team_slug}/{role_id}\n```\n\nAssigns an enterprise role to a team in an enterprise.\nWarning\n\nThis API is not available for Copilot Business for non-GHE.\n\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission write_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`team_slug`** (string) (required)\n  The slug of the enterprise team name.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n### HTTP response status codes\n\n- **204** - No Content\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **422** - Response if the enterprise roles feature is not enabled for the enterprise, or validation failed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X PUT \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/teams/TEAM_SLUG/ROLE_ID\n```\n\n**Response schema (Status: 204):**\n\n## Remove an enterprise role from a team\n\n```\nDELETE /enterprises/{enterprise}/enterprise-roles/teams/{team_slug}/{role_id}\n```\n\nRemoves an enterprise role from a team in an enterprise.\nWarning\n\nThis API is not available for Copilot Business for non-GHE.\n\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission write_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`team_slug`** (string) (required)\n  The slug of the enterprise team name.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n### HTTP response status codes\n\n- **204** - No Content\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **422** - Response if the enterprise roles feature is not enabled for the enterprise, or validation failed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X DELETE \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/teams/TEAM_SLUG/ROLE_ID\n```\n\n**Response schema (Status: 204):**\n\n## Remove all enterprise roles from a user\n\n```\nDELETE /enterprises/{enterprise}/enterprise-roles/users/{username}\n```\n\nRemoves all enterprise roles from an enterprise user in an enterprise.\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission write_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`username`** (string) (required)\n  The handle for the GitHub user account.\n\n### HTTP response status codes\n\n- **204** - No Content\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **422** - Response if the enterprise roles feature is not enabled for the enterprise, or validation failed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X DELETE \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/users/USERNAME\n```\n\n**Response schema (Status: 204):**\n\n## Assign an enterprise role to an enterprise user\n\n```\nPUT /enterprises/{enterprise}/enterprise-roles/users/{username}/{role_id}\n```\n\nAssigns an enterprise role to a user in an enterprise.\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission write_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`username`** (string) (required)\n  The handle for the GitHub user account.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n### HTTP response status codes\n\n- **204** - No Content\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **422** - Response if the enterprise roles feature is not enabled for the enterprise, or validation failed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X PUT \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/users/USERNAME/ROLE_ID\n```\n\n**Response schema (Status: 204):**\n\n## Remove enterprise user role assignment\n\n```\nDELETE /enterprises/{enterprise}/enterprise-roles/users/{username}/{role_id}\n```\n\nRemoves an enterprise role from an enterprise user.\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission write_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`username`** (string) (required)\n  The handle for the GitHub user account.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n### HTTP response status codes\n\n- **204** - No Content\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **422** - Response if the enterprise roles feature is not enabled for the enterprise, or validation failed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X DELETE \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/users/USERNAME/ROLE_ID\n```\n\n**Response schema (Status: 204):**\n\n## Get an enterprise role\n\n```\nGET /enterprises/{enterprise}/enterprise-roles/{role_id}\n```\n\nGets a custom enterprise role that is available within the enterprise.\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission read_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n### HTTP response status codes\n\n- **200** - OK\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/ROLE_ID\n```\n\n**Response schema (Status: 200):**\n\n* `id`: required, integer, format: int64\n* `name`: required, string\n* `description`: string or null\n* `source`: string or null, enum: `Enterprise`, `Predefined`, `null`\n* `permissions`: required, array of string\n* `enterprise`: required, any of:\n  * **null**\n  * **Enterprise**\n    * `description`: string or null\n    * `html_url`: required, string, format: uri\n    * `website_url`: string or null, format: uri\n    * `id`: required, integer\n    * `node_id`: required, string\n    * `name`: required, string\n    * `slug`: required, string\n    * `created_at`: required, string or null, format: date-time\n    * `updated_at`: required, string or null, format: date-time\n    * `avatar_url`: required, string, format: uri\n* `created_at`: required, string, format: date-time\n* `updated_at`: required, string, format: date-time\n\n## List teams that are assigned to an enterprise role\n\n```\nGET /enterprises/{enterprise}/enterprise-roles/{role_id}/teams\n```\n\nLists the teams that are assigned to an enterprise role.\nWarning\n\nThis API is not available for Copilot Business for non-GHE.\n\nTo use this endpoint, the authenticated user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission read_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) require the read:enterprise scope to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n- **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n- **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n- **200** - OK\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/ROLE_ID/teams\n```\n\n**Response schema (Status: 200):**\n\nArray of `Enterprise Team`:\n  * `id`: required, integer, format: int64\n  * `name`: required, string\n  * `description`: string\n  * `slug`: required, string\n  * `url`: required, string, format: uri\n  * `sync_to_organizations`: string\n  * `organization_selection_type`: string\n  * `group_id`: required, string or null\n  * `group_name`: string or null\n  * `html_url`: required, string, format: uri\n  * `members_url`: required, string\n  * `created_at`: required, string, format: date-time\n  * `updated_at`: required, string, format: date-time\n  * `notification_setting`: string, enum: `notifications_enabled`, `notifications_disabled`\n\n## List users that are assigned to an enterprise role\n\n```\nGET /enterprises/{enterprise}/enterprise-roles/{role_id}/users\n```\n\nLists enterprise members that are assigned to an enterprise role.\nTo use this endpoint, a user must be one of:\n\nAn administrator for the enterprise.\nA user, or a user on a team, with the fine-grained permission read_enterprise_custom_enterprise_role in the enterprise.\n\nOAuth app tokens and personal access tokens (classic) require the enterprise:admin scope to access this endpoint.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`role_id`** (integer) (required)\n  The unique identifier of the role.\n\n- **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n- **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n- **200** - Response - List of assigned users\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/enterprise-roles/ROLE_ID/users\n```\n\n**Response schema (Status: 200):**\n\nArray of `An Enterprise Role Assignment for a User` objects: all of:\n  * **Simple User**\n    * `name`: string or null\n    * `email`: string or null\n    * `login`: required, string\n    * `id`: required, integer, format: int64\n    * `node_id`: required, string\n    * `avatar_url`: required, string, format: uri\n    * `gravatar_id`: required, string or null\n    * `url`: required, string, format: uri\n    * `html_url`: required, string, format: uri\n    * `followers_url`: required, string, format: uri\n    * `following_url`: required, string\n    * `gists_url`: required, string\n    * `starred_url`: required, string\n    * `subscriptions_url`: required, string, format: uri\n    * `organizations_url`: required, string, format: uri\n    * `repos_url`: required, string, format: uri\n    * `events_url`: required, string\n    * `received_events_url`: required, string, format: uri\n    * `type`: required, string\n    * `site_admin`: required, boolean\n    * `starred_at`: string\n    * `user_view_type`: string\n  * **object**\n    * `assignment`: string, enum: `direct`, `indirect`, `mixed`\n    * `inherited_from`: array of `Enterprise Team`:\n      * `id`: required, integer, format: int64\n      * `name`: required, string\n      * `description`: string\n      * `slug`: required, string\n      * `url`: required, string, format: uri\n      * `sync_to_organizations`: string\n      * `organization_selection_type`: string\n      * `group_id`: required, string or null\n      * `group_name`: string or null\n      * `html_url`: required, string, format: uri\n      * `members_url`: required, string\n      * `created_at`: required, string, format: date-time\n      * `updated_at`: required, string, format: date-time\n      * `notification_setting`: string, enum: `notifications_enabled`, `notifications_disabled`"}