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.

“Get all enterprise roles for an enterprise”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (read)

“Get all enterprise roles for an enterprise”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.

“Get all enterprise roles for an enterprise”的 HTTP 响应状态代码

状态代码	说明
`200`	Response - list of enterprise roles
`403`	Forbidden
`404`	Resource not found

“Get all enterprise roles for an enterprise”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“Remove all enterprise roles from a team”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (write)

“Remove all enterprise roles from a team”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`team_slug` string 必须 The slug of the enterprise team name.

“Remove all enterprise roles from a team”的 HTTP 响应状态代码

状态代码	说明
`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.

“Remove all enterprise roles from a team”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“Assign an enterprise role to a team”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (write)

“Assign an enterprise role to a team”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`team_slug` string 必须 The slug of the enterprise team name.
`role_id` integer 必须 The unique identifier of the role.

“Assign an enterprise role to a team”的 HTTP 响应状态代码

状态代码	说明
`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.

“Assign an enterprise role to a team”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“Remove an enterprise role from a team”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (write)

“Remove an enterprise role from a team”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`team_slug` string 必须 The slug of the enterprise team name.
`role_id` integer 必须 The unique identifier of the role.

“Remove an enterprise role from a team”的 HTTP 响应状态代码

状态代码	说明
`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.

“Remove an enterprise role from a team”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“Remove all enterprise roles from a user”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (write)

“Remove all enterprise roles from a user”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`username` string 必须 The handle for the GitHub user account.

“Remove all enterprise roles from a user”的 HTTP 响应状态代码

状态代码	说明
`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.

“Remove all enterprise roles from a user”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“Assign an enterprise role to an enterprise user”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (write)

“Assign an enterprise role to an enterprise user”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`username` string 必须 The handle for the GitHub user account.
`role_id` integer 必须 The unique identifier of the role.

“Assign an enterprise role to an enterprise user”的 HTTP 响应状态代码

状态代码	说明
`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.

“Assign an enterprise role to an enterprise user”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“Remove enterprise user role assignment”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (write)

“Remove enterprise user role assignment”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`username` string 必须 The handle for the GitHub user account.
`role_id` integer 必须 The unique identifier of the role.

“Remove enterprise user role assignment”的 HTTP 响应状态代码

状态代码	说明
`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.

“Remove enterprise user role assignment”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“Get an enterprise role”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (read)

“Get an enterprise role”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`role_id` integer 必须 The unique identifier of the role.

“Get an enterprise role”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found

“Get an enterprise role”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“List teams that are assigned to an enterprise role”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (read)

“List teams that are assigned to an enterprise role”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`role_id` integer 必须 The unique identifier of the role.

查询参数
名称, 类型, 说明
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." 默认: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." 默认: `1`

“List teams that are assigned to an enterprise role”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found

“List teams that are assigned to an enterprise role”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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.

“List users that are assigned to an enterprise role”的细粒度访问令牌

此端点支持以下精细令牌类型:

精细令牌必须具有以下权限集:

"Custom enterprise roles" enterprise permissions (read)

“List users that are assigned to an enterprise role”的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`enterprise` string 必须 The slug version of the enterprise name.
`role_id` integer 必须 The unique identifier of the role.

查询参数
名称, 类型, 说明
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." 默认: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." 默认: `1`

“List users that are assigned to an enterprise role”的 HTTP 响应状态代码

状态代码	说明
`200`	Response - List of assigned users
`403`	Forbidden
`404`	Resource not found

“List users that are assigned to an enterprise role”的示例代码

如果你通过 GHE.com 访问 GitHub，请将 api.github.com 替换为你的企业在 api.SUBDOMAIN.ghe.com 上的专用子域。

请求示例

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