Many of the resources on the users API provide a shortcut for getting information about the currently authenticated user. If a request URL does not include a {username}
parameter then the response will be for the logged in user (and you must pass authentication information with your request). Additional private information, such as whether a user has two-factor authentication enabled, is included when authenticated through basic auth or OAuth with the user
scope.
Get the authenticated user
If the authenticated user is authenticated through basic authentication or OAuth with the user
scope, then the response lists public and private profile information.
If the authenticated user is authenticated through OAuth without the user
scope, then the response lists only public profile information.
get /user
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user
JavaScript (@octokit/core.js)
await octokit.request('GET /user')
Response with public and private profile information
Status: 200 OK
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z",
"private_gists": 81,
"total_private_repos": 100,
"owned_private_repos": 100,
"disk_usage": 10000,
"collaborators": 8,
"two_factor_authentication": true,
"plan": {
"name": "Medium",
"space": 400,
"private_repos": 20,
"collaborators": 0
}
}
Response with public profile information
Status: 200 OK
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z"
}
Update the authenticated user
Note: If your email is set to private and you send an email
parameter as part of this request to update your profile, your privacy settings are still enforced: the email address will not be displayed on your public profile or via the API.
patch /user
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
name |
string | body |
The new name of the user. |
email |
string | body |
The publicly visible email address of the user. |
blog |
string | body |
The new blog URL of the user. |
company |
string | body |
The new company of the user. |
location |
string | body |
The new location of the user. |
hireable |
boolean | body |
The new hiring availability of the user. |
bio |
string | body |
The new short biography of the user. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /user', {
name: 'name'
})
Default response
Status: 200 OK
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z",
"private_gists": 81,
"total_private_repos": 100,
"owned_private_repos": 100,
"disk_usage": 10000,
"collaborators": 8,
"two_factor_authentication": true,
"plan": {
"name": "Medium",
"space": 400,
"private_repos": 20,
"collaborators": 0
}
}
List users
Lists all users, in the order that they signed up on GitHub Enterprise. This list includes personal user accounts and organization accounts.
Note: Pagination is powered exclusively by the since
parameter. Use the Link header to get the URL for the next page of users.
get /users
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
since |
string | query |
The integer ID of the last User that you've seen. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/users
JavaScript (@octokit/core.js)
await octokit.request('GET /users')
Default response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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
}
]
Notes
Get a user
Provides publicly available information about someone with a GitHub Enterprise account.
The email
key in the following response is the publicly visible email address from your GitHub Enterprise profile page. When setting up your profile, you can select a primary email address to be “public” which provides an email entry for this endpoint. If you do not set a public email address for email
, then it will have a value of null
. You only see publicly visible email addresses when authenticated with GitHub Enterprise. For more information, see Authentication.
The Emails API enables you to list all of your email addresses, and toggle a primary email to be visible publicly. For more information, see "Emails API".
get /users/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/users/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}', {
username: 'username'
})
Default response
Status: 200 OK
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z"
}
Notes
Get contextual information for a user
Provides hovercard information when authenticated through basic auth or OAuth with the repo
scope. You can find out more about someone in relation to their pull requests, issues, repositories, and organizations.
The subject_type
and subject_id
parameters provide context for the person's hovercard, which returns more information than without the parameters. For example, if you wanted to find out more about octocat
who owns the Spoon-Knife
repository via cURL, it would look like this:
curl -u username:token
https://api.github.com/users/octocat/hovercard?subject_type=repository&subject_id=1300192
get /users/{username}/hovercard
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change. See preview notice. |
username |
string | path | |
subject_type |
string | query |
Identifies which additional information you'd like to receive about the person's hovercard. Can be |
subject_id |
string | query |
Uses the ID for the |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.hagar-preview+json" \
https://{hostname}/users/USERNAME/hovercard
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}/hovercard', {
username: 'username',
mediaType: {
previews: [
'hagar'
]
}
})
Default response
Status: 200 OK
{
"contexts": [
{
"message": "Owns this repository",
"octicon": "repo"
}
]
}
Preview notice
You can now retrieve someone's hovercard information in different contexts using the Hovercard API. This feature is currently available for developers to preview. See the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.hagar-preview+json
☝️ This header is required.
Blocking users
Emails
Management of email addresses via the API requires that you authenticate through basic auth, or through OAuth with a correct scope for the endpoint.
List email addresses for the authenticated user
Lists all of your email addresses, and specifies which one is visible to the public. This endpoint is accessible with the user:email
scope.
get /user/emails
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/emails
JavaScript (@octokit/core.js)
await octokit.request('GET /user/emails')
Default response
Status: 200 OK
[
{
"email": "octocat@github.com",
"verified": true,
"primary": true,
"visibility": "public"
}
]
Add an email address for the authenticated user
If your GitHub Enterprise Server instance has LDAP Sync enabled and the option to synchronize emails enabled, this API is disabled and will return a 403
response. Users managed in LDAP won't be able to add or delete an email address via the API with these options enabled.
This endpoint is accessible with the user
scope.
post /user/emails
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
emails |
array of strings | body |
Required. Adds one or more email addresses to your GitHub Enterprise account. Must contain at least one email address. Note: Alternatively, you can pass a single email address or an |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/emails \
-d '{"emails":["octocat@github.com"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /user/emails', {
emails: [
'octocat@github.com'
]
})
Default response
Status: 201 Created
[
{
"email": "octocat@octocat.org",
"primary": false,
"verified": false,
"visibility": "public"
},
{
"email": "octocat@github.com",
"primary": false,
"verified": false,
"visibility": null
},
{
"email": "support@github.com",
"primary": false,
"verified": false,
"visibility": null
}
]
Delete an email address for the authenticated user
If your GitHub Enterprise Server instance has LDAP Sync enabled and the option to synchronize emails enabled, this API is disabled and will return a 403
response. Users managed in LDAP won't be able to add or delete an email address via the API with these options enabled.
This endpoint is accessible with the user
scope.
delete /user/emails
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
emails |
array of strings | body |
Required. Deletes one or more email addresses from your GitHub Enterprise account. Must contain at least one email address. Note: Alternatively, you can pass a single email address or an |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/emails \
-d '{"emails":["octocat@github.com"]}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /user/emails', {
emails: [
'octocat@github.com'
]
})
Default Response
Status: 204 No Content
List public email addresses for the authenticated user
Lists your publicly visible email address. This endpoint is accessible with the user:email
scope.
get /user/public_emails
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/public_emails
JavaScript (@octokit/core.js)
await octokit.request('GET /user/public_emails')
Default response
Status: 200 OK
[
{
"email": "octocat@github.com",
"verified": true,
"primary": true,
"visibility": "public"
}
]
Follower
List followers of the authenticated user
Lists the people following the authenticated user.
get /user/followers
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/followers
JavaScript (@octokit/core.js)
await octokit.request('GET /user/followers')
Default response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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
}
]
List the people the authenticated user follows
Lists the people who the authenticated user follows.
get /user/following
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/following
JavaScript (@octokit/core.js)
await octokit.request('GET /user/following')
Default response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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
}
]
get /user/following/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/following/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('GET /user/following/{username}', {
username: 'username'
})
Response if the person is followed by the authenticated user
Status: 204 No Content
Response if the person is not followed by the authenticated user
Status: 404 Not Found
Follow a user
Note that you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP verbs."
Following a user requires the user to be logged in and authenticated with basic auth or OAuth with the user:follow
scope.
put /user/following/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/following/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('PUT /user/following/{username}', {
username: 'username'
})
Default Response
Status: 204 No Content
Unfollow a user
Unfollowing a user requires the user to be logged in and authenticated with basic auth or OAuth with the user:follow
scope.
delete /user/following/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/following/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /user/following/{username}', {
username: 'username'
})
Default Response
Status: 204 No Content
List followers of a user
Lists the people following the specified user.
get /users/{username}/followers
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/users/USERNAME/followers
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}/followers', {
username: 'username'
})
Default response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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
}
]
Notes
List the people a user follows
Lists the people who the specified user follows.
get /users/{username}/following
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/users/USERNAME/following
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}/following', {
username: 'username'
})
Default response
Status: 200 OK
[
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"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
}
]
Notes
get /users/{username}/following/{target_user}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path | |
target_user |
string | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/users/USERNAME/following/TARGET_USER
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}/following/{target_user}', {
username: 'username',
target_user: 'target_user'
})
Response if the user follows the target user
Status: 204 No Content
Response if the user does not follow the target user
Status: 404 Not Found
Notes
Git SSH keys
List public SSH keys for the authenticated user
Lists the public SSH keys for the authenticated user's GitHub account. Requires that you are authenticated via Basic Auth or via OAuth with at least read:public_key
scope.
get /user/keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/keys
JavaScript (@octokit/core.js)
await octokit.request('GET /user/keys')
Default response
Status: 200 OK
[
{
"key_id": "012345678912345678",
"key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234"
}
]
Create a public SSH key for the authenticated user
Adds a public SSH key to the authenticated user's GitHub account. Requires that you are authenticated via Basic Auth, or OAuth with at least write:public_key
scope.
If your GitHub Enterprise Server appliance has LDAP Sync enabled and the option to synchronize SSH keys enabled, this API is disabled and will return a 403
response. Users managed in LDAP won't be able to add an SSH key address via the API with these options enabled.
post /user/keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
title |
string | body |
A descriptive name for the new key. Use a name that will help you recognize this key in your GitHub account. For example, if you're using a personal Mac, you might call this key "Personal MacBook Air". |
key |
string | body |
The public SSH key to add to your GitHub account. See "Generating a new SSH key" for guidance on how to create a public SSH key. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/keys \
-d '{"title":"title"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /user/keys', {
title: 'title'
})
Default response
Status: 201 Created
{
"key_id": "012345678912345678",
"key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234"
}
Get a public SSH key for the authenticated user
View extended details for a single public SSH key. Requires that you are authenticated via Basic Auth or via OAuth with at least read:public_key
scope.
get /user/keys/{key_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
key_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/keys/42
JavaScript (@octokit/core.js)
await octokit.request('GET /user/keys/{key_id}', {
key_id: 42
})
Default response
Status: 200 OK
{
"key_id": "012345678912345678",
"key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234"
}
Delete a public SSH key for the authenticated user
Removes a public SSH key from the authenticated user's GitHub account. Requires that you are authenticated via Basic Auth or via OAuth with at least admin:public_key
scope.
If your GitHub Enterprise Server appliance has LDAP Sync enabled and the option to synchronize SSH keys enabled, this API is disabled and will return a 403
response. Users managed in LDAP won't be able to remove an SSH key address via the API with these options enabled.
delete /user/keys/{key_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
key_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/user/keys/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /user/keys/{key_id}', {
key_id: 42
})
Default Response
Status: 204 No Content
List public keys for a user
Lists the verified public SSH keys for a user. This is accessible by anyone.
get /users/{username}/keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to |
username |
string | path | |
per_page |
integer | query |
Results per page (max 100) |
page |
integer | query |
Page number of the results to fetch. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
https://{hostname}/users/USERNAME/keys
JavaScript (@octokit/core.js)
await octokit.request('GET /users/{username}/keys', {
username: 'username'
})
Default response
Status: 200 OK
[
{
"id": 1,
"key": "ssh-rsa AAA..."
}
]
Notes
GPG keys
The data returned in the public_key
response field is not a GPG formatted key. When a user uploads a GPG key, it is parsed and the cryptographic public key is extracted and stored. This cryptographic key is what is returned by the APIs on this page. This key is not suitable to be used directly by programs like GPG.