适用于企业用户的 REST API 终结点

关于用户管理

这些终结点仅适用于经过身份验证的网站管理员。普通用户将收到 403 响应。

List public keys

“List public keys”的参数

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

查询参数
名称, 类型, 说明
`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`
`direction` string The direction to sort the results by. 默认: `desc` 可以是以下选项之一: `asc`, `desc`
`sort` string 默认: `created` 可以是以下选项之一: `created`, `updated`, `accessed`
`since` string Only show public keys accessed after the given time.

“List public keys”的 HTTP 响应状态代码

状态代码	说明
`200`	OK

“List public keys”的示例代码

请求示例

get/admin/keys

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/keys

Response

Status: 200

[
  {
    "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
    "id": 2,
    "url": "https://HOSTNAME/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  },
  {
    "key": "9Og8iYjAyymI9LvABpJerYrMxURPc8r+dB7TJyvv1234",
    "id": 3,
    "url": "https://HOSTNAME/user/keys/2",
    "title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
    "created_at": "2020-06-11T21:31:57Z",
    "verified": false,
    "read_only": false,
    "last_used": "2020-06-11T22:31:57Z",
    "user_id": 1,
    "repository_id": 2
  }
]

Delete a public key

“Delete a public key”的参数

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

路径参数
名称, 类型, 说明
`key_ids` string 必须 The unique identifier of the key.

“Delete a public key”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Delete a public key”的示例代码

请求示例

delete/admin/keys/{key_ids}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/keys/KEY_IDS

Response

Status: 204

List personal access tokens

Lists personal access tokens for all users, including admin users.

“List personal access tokens”的参数

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

查询参数
名称, 类型, 说明
`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 personal access tokens”的 HTTP 响应状态代码

状态代码	说明
`200`	OK

“List personal access tokens”的示例代码

请求示例

get/admin/tokens

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/tokens

Response

Status: 200

[
  {
    "id": 2,
    "url": "https://enterprise.octocat.com/api/v3/authorizations/2",
    "app": {
      "name": "My personal access token",
      "url": "https://docs.github.com/enterprise/rest/enterprise-admin/users#list-personal-access-tokens",
      "client_id": "00000000000000000000"
    },
    "token": "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "Ae178B4a",
    "note": "My personal access token",
    "note_url": null,
    "created_at": "2019-04-24T21:49:02Z",
    "updated_at": "2019-04-24T21:49:02Z",
    "scopes": [
      "admin:business",
      "admin:gpg_key",
      "admin:org",
      "admin:org_hook",
      "admin:pre_receive_hook",
      "admin:public_key",
      "admin:repo_hook",
      "delete_repo",
      "gist",
      "notifications",
      "repo",
      "user",
      "write:discussion"
    ],
    "fingerprint": null
  }
]

Delete a personal access token

Deletes a personal access token. Returns a 403 - Forbidden status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.

“Delete a personal access token”的参数

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

路径参数
名称, 类型, 说明
`token_id` integer 必须 The unique identifier of the token.

“Delete a personal access token”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Delete a personal access token”的示例代码

请求示例

delete/admin/tokens/{token_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/tokens/TOKEN_ID

Response

Status: 204

Create a user

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send "octo_cat" as the login, a user named "octo-cat" will be created.

If the login name or email address is already associated with an account, the server will return a 422 response.

“Create a user”的参数

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

正文参数
名称, 类型, 说明
`login` string 必须 The user's username.
`email` string Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For more information, see "About authentication for your enterprise."
`suspended` boolean Whether to set the user as suspended when the user is created. 默认: `false`

“Create a user”的 HTTP 响应状态代码

状态代码	说明
`201`	Created

“Create a user”的示例代码

请求示例

post/admin/users

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/users \
  -d '{"login":"monalisa","email":"octocat@github.com"}'

Response

Status: 201

{
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://HOSTNAME/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://HOSTNAME/users/octocat/followers",
  "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
  "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
  "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
  "organizations_url": "https://HOSTNAME/users/octocat/orgs",
  "repos_url": "https://HOSTNAME/users/octocat/repos",
  "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
  "received_events_url": "https://HOSTNAME/users/octocat/received_events",
  "type": "User",
  "site_admin": false
}

Update the username for a user

“Update the username for a user”的参数

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

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

正文参数
名称, 类型, 说明
`login` string 必须 The user's new username.

“Update the username for a user”的 HTTP 响应状态代码

状态代码	说明
`202`	Accepted

“Update the username for a user”的示例代码

请求示例

patch/admin/users/{username}

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME \
  -d '{"login":"thenewmonalisa"}'

Response

Status: 202

{
  "message": "Job queued to rename user. It may take a few minutes to complete.",
  "url": "https://HOSTNAME/user/1"
}

Delete a user

Deleting a user will delete all their repositories, gists, applications, and personal settings. Suspending a user is often a better option.

You can delete any user account except your own.

“Delete a user”的参数

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

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

“Delete a user”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Delete a user”的示例代码

请求示例

delete/admin/users/{username}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME

Response

Status: 204

Create an impersonation OAuth token

“Create an impersonation OAuth token”的参数

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

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

正文参数
名称, 类型, 说明
`scopes` array of strings 必须 A list of scopes.

“Create an impersonation OAuth token”的 HTTP 响应状态代码

状态代码	说明
`200`	Response when getting an existing impersonation OAuth token
`201`	Response when creating a new impersonation OAuth token

“Create an impersonation OAuth token”的示例代码

请求示例

Select the example type

post/admin/users/{username}/authorizations

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME/authorizations \
  -d '{"scopes":["public_repo"]}'

Response when getting an existing impersonation OAuth token

Status: 200

{
  "id": 1,
  "url": "https://HOSTNAME/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_last_eight": "Ae178B4a",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "expires_at": "2011-10-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Delete an impersonation OAuth token

“Delete an impersonation OAuth token”的参数

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

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

“Delete an impersonation OAuth token”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Delete an impersonation OAuth token”的示例代码

请求示例

delete/admin/users/{username}/authorizations

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/admin/users/USERNAME/authorizations

Response

Status: 204

Promote a user to be a site administrator

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP method."

“Promote a user to be a site administrator”的参数

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

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

“Promote a user to be a site administrator”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Promote a user to be a site administrator”的示例代码

请求示例

put/users/{username}/site_admin

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/site_admin

Response

Status: 204

Demote a site administrator

You can demote any user account except your own.

“Demote a site administrator”的参数

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

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

“Demote a site administrator”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Demote a site administrator”的示例代码

请求示例

delete/users/{username}/site_admin

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/site_admin

Response

Status: 204

Suspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, Active Directory LDAP-authenticated users cannot be suspended through this API. If you attempt to suspend an Active Directory LDAP-authenticated user through this API, it will return a 403 response.

You can suspend any user account except your own.

Note that, if you choose not to pass any parameters, you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP method."

“Suspend a user”的参数

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

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

正文参数
名称, 类型, 说明
`reason` string The reason the user is being suspended. This message will be logged in the audit log. If you don't provide a `reason`, it will default to "Suspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

“Suspend a user”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Suspend a user”的示例代码

请求示例

put/users/{username}/suspended

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/suspended \
  -d '{"reason":"Suspended during leave of absence."}'

Response

Status: 204

Unsuspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, this API is disabled and will return a 403 response. Active Directory LDAP-authenticated users cannot be unsuspended using the API.

“Unsuspend a user”的参数

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

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

正文参数
名称, 类型, 说明
`reason` string The reason the user is being unsuspended. This message will be logged in the audit log. If you don't provide a `reason`, it will default to "Unsuspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

“Unsuspend a user”的 HTTP 响应状态代码

状态代码	说明
`204`	No Content

“Unsuspend a user”的示例代码

请求示例

delete/users/{username}/suspended

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/users/USERNAME/suspended \
  -d '{"reason":"Unsuspended after leave of absence."}'

Response

Status: 204