Skip to content

Commit 5c754a8

Browse files
izuzakizuzak
committed
Merge branch public/master into internal/master
2 parents 118dfa5 + 8fedece commit 5c754a8

6 files changed

Lines changed: 62 additions & 323 deletions

File tree

‎content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
kind: change
3+
title: Finer-grained OAuth scopes for SSH keys
4+
created_at: 2014-02-24
5+
author_name: pengwynn
6+
---
7+
As [we announced][blog], we've made some important changes to the way that API consumers manage SSH keys.
8+
9+
## Finer-grained OAuth scopes
10+
11+
To help third party applications request only permissions that they need, the API now supports three new [scopes][] for working with a user's public SSH keys.
12+
13+
- `read:public_key` provides read access to the user's SSH keys
14+
- `write:public_key` allows an app to read existing keys and create new ones
15+
- `admin:public_key` enables an app to read, write, and delete keys
16+
17+
## Changes to `user` scope
18+
19+
Historically, `user` scope has provided full access to manage a user's SSH keys. Now that we have dedicated scopes for managing a user's SSH keys, we have removed those permissions from the `user` scope. Now `user` scope will no longer provide access to SSH keys. Applications that need this access should request one of the new scopes described above.
20+
21+
## Keys are now immutable
22+
23+
To simplify the security audit trail for SSH keys, we're making keys immutable. API consumers can continue to create keys and delete keys as needed, but keys can no longer be changed. To change an existing key, API consumers should delete the existing key and create a new one with the desired attributes. This change applies both to a [user's SSH keys][user-keys] and a [repository's deploy keys][deploy-keys].
24+
25+
## Deleting keys when revoking a token
26+
27+
Also any keys created via an OAuth token from this point forward will be deleted when that token is revoked.
28+
29+
As always, if you have any questions or feedback, [please get in touch][contact].
30+
31+
[contact]: https://github.com/contact?form[subject]=API+improvements+for+SSH+keys
32+
[scopes]: /v3/oauth/#scopes
33+
[user-keys]: /v3/users/keys/
34+
[deploy-keys]: /v3/repos/keys/
35+
[blog]: https://github.com/blog/1786-enhanced-oauth-security-for-ssh-keys

‎content/v3/oauth.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,9 @@ Name | Description
183183
`read:repo_hook`| Grants read and ping access to hooks in public or private repositories.
184184
`write:repo_hook`| Grants read, write, and ping access to hooks in public or private repositories.
185185
`admin:repo_hook`| Grants read, write, ping, and delete access to hooks in public or private repositories.
186+
`read:public_key`| List and view details for public keys.
187+
`write:public_key`| Create, list, and view details for public keys.
188+
`admin:public_key`| Fully manage public keys.
186189

187190
NOTE: Your application can request the scopes in the initial redirection. You
188191
can specify multiple scopes by separating them with a comma:
@@ -351,6 +354,8 @@ registered with your application.
351354

352355
### Bad verification code
353356

357+
<%= json :add_scopes => ['repo'], :note => 'admin script' %>
358+
354359
If the verification code you pass is incorrect, expired, or doesn't
355360
match what you received in the first request for authorization you will
356361
receive this error.
@@ -368,3 +373,4 @@ and get a new code.
368373
[oauth changes blog]: /changes/2013-10-04-oauth-changes-coming/
369374
[basics auth guide]: /guides/basics-of-authentication/
370375
[deployments]: /v3/repos/deployments
376+
[public keys]: /v3/users/keys/

‎content/v3/orgs/teams.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,9 @@ organization, you get:
205205
## Remove team repository {#remove-team-repo}
206206

207207
In order to remove a repository from a team, the authenticated user must be an
208-
owner of the org that the team is associated with.
208+
owner of the org that the team is associated with. Also, since the Owners team
209+
always has access to all repositories in the organization, repositories cannot
210+
be removed from the Owners team.
209211
NOTE: This does not delete the repository, it just removes it from the team.
210212

211213
DELETE /teams/:id/repos/:owner/:repo

‎content/v3/repos/keys.md‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -40,16 +40,8 @@ title: Deploy Keys | GitHub API
4040

4141
## Edit a deploy key {#edit}
4242

43-
PATCH /repos/:owner/:repo/keys/:id
44-
45-
### Input
46-
47-
<%= json :title => "octocat@octomac", :key => "ssh-rsa AAA..." %>
48-
49-
### Response
50-
51-
<%= headers 200 %>
52-
<%= json :public_key %>
43+
Deploy keys are immutable. If you need to update a key, [remove the
44+
key](#delete) and [create a new one](#create) instead.
5345

5446
## Remove a deploy key {#delete}
5547

‎content/v3/users/keys.md‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,9 @@ Lists the _verified_ public keys for a user. This is accessible by anyone.
2323

2424
GET /user/keys
2525

26-
Lists the current user's keys. Management of public keys via the API requires
27-
that you are authenticated through basic auth, or OAuth with the 'user' scope.
26+
Lists the current user's keys. Requires that you are authenticated via
27+
Basic Auth or via OAuth with at least `read:public_key`
28+
[scope](/v3/oauth/#scopes).
2829

2930
### Response
3031

@@ -33,6 +34,10 @@ that you are authenticated through basic auth, or OAuth with the 'user' scope.
3334

3435
## Get a single public key
3536

37+
View extended details for a single public key. Requires that you are
38+
authenticated via Basic Auth or via OAuth with at least `read:public_key`
39+
[scope](/v3/oauth/#scopes).
40+
3641
GET /user/keys/:id
3742

3843
### Response
@@ -42,6 +47,9 @@ that you are authenticated through basic auth, or OAuth with the 'user' scope.
4247

4348
## Create a public key
4449

50+
Creates a public key. Requires that you are authenticated via Basic Auth,
51+
or OAuth with at least `write:public_key` [scope](/v3/oauth/#scopes).
52+
4553
POST /user/keys
4654

4755
### Input
@@ -55,19 +63,15 @@ that you are authenticated through basic auth, or OAuth with the 'user' scope.
5563

5664
## Update a public key
5765

58-
PATCH /user/keys/:id
59-
60-
### Input
61-
62-
<%= json :title => "octocat@octomac", :key => "ssh-rsa AAA..." %>
63-
64-
### Response
65-
66-
<%= headers 200 %>
67-
<%= json :public_key %>
66+
Public keys are immutable. If you need to update a public key, [remove the
67+
key](#delete-a-public-key) and [create a new one](#create-a-public-key)
68+
instead.
6869

6970
## Delete a public key
7071

72+
Removes a public key. Requires that you are authenticated via Basic Auth
73+
or via OAuth with at least `admin:public_key` [scope](/v3/oauth/#scopes).
74+
7175
DELETE /user/keys/:id
7276

7377
### Response

0 commit comments

Comments
 (0)