Merge public-key-scope-changes

pengwynn · pengwynn · commit 55264c4360a2 · 2014-02-24T18:56:29.000-06:00
diff --git a/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md b/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md
@@ -0,0 +1,35 @@
+---
+kind: change
+title: Finer-grained OAuth scopes for SSH keys
+created_at: 2014-02-24
+author_name: pengwynn
+---
+As [we announced][blog], we've made some important changes to the way that API consumers manage SSH keys.
+
+## Finer-grained OAuth scopes
+
+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.
+
+- `read:public_key` provides read access to the user's SSH keys
+- `write:public_key` allows an app to read existing keys and create new ones
+- `admin:public_key` enables an app to read, write, and delete keys
+
+## Changes to `user` scope
+
+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.
+
+## Keys are now immutable
+
+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].
+
+## Deleting keys when revoking a token
+
+Also any keys created via an OAuth token from this point forward will be deleted when that token is revoked.
+
+As always, if you have any questions or feedback, [please get in touch][contact].
+
+[contact]: https://github.com/contact?form[subject]=API+improvements+for+SSH+keys
+[scopes]: /v3/oauth/#scopes
+[user-keys]: /v3/users/keys/
+[deploy-keys]: /v3/repos/keys/
+[blog]: https://github.com/blog/1786-enhanced-oauth-security-for-ssh-keys
diff --git a/content/v3/oauth.md b/content/v3/oauth.md
@@ -174,6 +174,9 @@ Name | Description
 `read:repo_hook`| Grants read and ping access to hooks in public or private repositories.
 `write:repo_hook`| Grants read, write, and ping access to hooks in public or private repositories.
 `admin:repo_hook`| Grants read, write, ping, and delete access to hooks in public or private repositories.
+`read:public_key`| List and view details for public keys.
+`write:public_key`| Create, list, and view details for public keys.
+`admin:public_key`| Fully manage public keys.
 
 NOTE: Your application can request the scopes in the initial redirection. You
 can specify multiple scopes by separating them with a comma:
@@ -299,6 +302,9 @@ You can only send one of these scope keys at a time.
 
 ## Delete an authorization
 
+Destroys an OAuth token and any [public keys][] previously created with that
+token.
+
     DELETE /authorizations/:id
 
 ### Response
@@ -368,3 +374,4 @@ links that might be of help:
 [oauth changes blog]: /changes/2013-10-04-oauth-changes-coming/
 [basics auth guide]: /guides/basics-of-authentication/
 [deployments]: /v3/repos/deployments
+[public keys]: /v3/users/keys/
diff --git a/content/v3/repos/keys.md b/content/v3/repos/keys.md
@@ -40,16 +40,8 @@ title: Deploy Keys | GitHub API
 
 ## Edit a deploy key {#edit}
 
-    PATCH /repos/:owner/:repo/keys/:id
-
-### Input
-
-<%= json :title => "octocat@octomac", :key => "ssh-rsa AAA..." %>
-
-### Response
-
-<%= headers 200 %>
-<%= json :public_key %>
+Deploy keys are immutable. If you need to update a key, [remove the
+key](#delete) and [create a new one](#create) instead.
 
 ## Remove a deploy key {#delete}
 
diff --git a/content/v3/users/keys.md b/content/v3/users/keys.md
@@ -23,8 +23,9 @@ Lists the _verified_ public keys for a user.  This is accessible by anyone.
 
     GET /user/keys
 
-Lists the current user's keys.  Management of public keys via the API requires
-that you are authenticated through basic auth, or OAuth with the 'user' scope.
+Lists the current user's keys. Requires that you are authenticated via
+Basic Auth or via OAuth with at least `read:public_key`
+[scope](/v3/oauth/#scopes).
 
 ### Response
 
@@ -33,6 +34,10 @@ that you are authenticated through basic auth, or OAuth with the 'user' scope.
 
 ## Get a single public key
 
+View extended details for a single public key. Requires that you are
+authenticated via Basic Auth or via OAuth with at least `read:public_key`
+[scope](/v3/oauth/#scopes).
+
     GET /user/keys/:id
 
 ### Response
@@ -42,6 +47,9 @@ that you are authenticated through basic auth, or OAuth with the 'user' scope.
 
 ## Create a public key
 
+Creates a public key. Requires that you are authenticated via Basic Auth,
+or OAuth with at least `write:public_key` [scope](/v3/oauth/#scopes).
+
     POST /user/keys
 
 ### Input
@@ -55,19 +63,15 @@ that you are authenticated through basic auth, or OAuth with the 'user' scope.
 
 ## Update a public key
 
-    PATCH /user/keys/:id
-
-### Input
-
-<%= json :title => "octocat@octomac", :key => "ssh-rsa AAA..." %>
-
-### Response
-
-<%= headers 200 %>
-<%= json :public_key %>
+Public keys are immutable. If you need to update a public key, [remove the
+key](#delete-a-public-key) and [create a new one](#create-a-public-key)
+instead.
 
 ## Delete a public key
 
+Removes a public key. Requires that you are authenticated via Basic Auth
+or via OAuth with at least `admin:public_key` [scope](/v3/oauth/#scopes).
+
     DELETE /user/keys/:id
 
 ### Response
