{"action":"created","comment":{"url":"https://api.github.com/repos/mozilla/fxa/pulls/comments/43348946","id":43348946,"diff_hunk":"@@ -0,0 +1,360 @@\n+# Device registration API\n+\n+https://mozilla.aha.io/features/FXA-45\n+\n+As a Firefox developer, I want\n+to be able to associate device details with an FxA login session,\n+and receive notifications when those details are changed on the server,\n+so that I can start building richer device-driven features\n+for the Firefox Connected Experience.\n+\n+* [Stories](#stories)\n+* [Data](#data)\n+* [API](#api)\n+  * [POST /v1/account/login](#post-v1accountlogin)\n+  * [POST /v1/account/create](#post-v1accountcreate)\n+  * [POST /v1/account/device](#post-v1accountdevice)\n+  * [POST /v1/account/device/destroy](#post-v1accountdevicedestroy)\n+  * [GET /v1/account/devices](#get-v1accountdevices)\n+* [Details](#details)\n+  * [What is a \"recovering device\"?](#what-is-a-recovering-device)\n+  * [How are shared devices handled?](#how-are-shared-devices-handled)\n+  * [Are shared devices bound to the account or the device?](#are-shared-devices-bound-to-the-account-or-the-device)\n+  * [How are unrecognised devices handled?](#how-are-unrecognised-devices-handled)\n+  * [How big should the device id be?](#how-big-should-the-device-id-be)\n+\n+## Stories\n+\n+Is it reasonable to break these down\n+one per endpoint?\n+\n+## Data\n+\n+```js\n+{\n+  // The user this device belongs to\n+  \"uid\": \"4c352927cd4f4a4aa03d7d1893d950b8\",\n+\n+  // The active session for this device\n+  \"sessionToken\": \"27cd4f4a4aa03d7d186a2ec81cbf19d5c8a604713362df9ee15c4f4a4aa03d7d\",\n+\n+  // A server assigned identifier for this device\n+  \"id\":\"01ab\",\n+\n+  // A human identifier for this devices. Able to be updated by the user\n+  \"name\": \"My Phone\",\n+\n+  // General type of device. Useful for device list icons and demographic metrics\n+  \"type\": \"mobile\",\n+\n+  // Timestamp of when the device was first created, à la Date.now()\n+  \"createdAt\": 1442785364807,\n+\n+  // The push notification endpoint for this device/user\n+  \"callback\": \"https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef\"\n+```\n+\n+## API\n+\n+### POST /v1/account/login\n+\n+Authenticated with session token or OAuth.\n+\n+#### Requests\n+\n+##### New device\n+\n+```\n+curl -v \\\n+-X POST \\\n+-H \"Host: api-accounts.dev.lcip.org\" \\\n+-H \"Content-Type: application/json\" \\\n+-H 'Authorization: Hawk id=\"d4c5b1e3f5791ef83896c27519979b93a45e6d0da34c7509c5632ac35b28b48d\", ts=\"1373391043\", nonce=\"ohQjqb\", hash=\"vBODPWhDhiRWM4tmI9qp+np+3aoqEFzdGuGk0h7bh9w=\", mac=\"LAnpP3P2PXelC6hUoUaHP72nCqY5Iibaa3eeiGBqIIU=\"' \\\n+https://api-accounts.dev.lcip.org/v1/account/device \\\n+-d '{\n+  \"name\": \"My Phone\",\n+  \"type\": \"mobile\",\n+  \"callback\": \"https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef\"\n+}'\n+```\n+\n+##### Registered device\n+\n+```\n+curl -v \\\n+-X POST \\\n+-H \"Host: api-accounts.dev.lcip.org\" \\\n+-H \"Content-Type: application/json\" \\\n+-H 'Authorization: Hawk id=\"d4c5b1e3f5791ef83896c27519979b93a45e6d0da34c7509c5632ac35b28b48d\", ts=\"1373391043\", nonce=\"ohQjqb\", hash=\"vBODPWhDhiRWM4tmI9qp+np+3aoqEFzdGuGk0h7bh9w=\", mac=\"LAnpP3P2PXelC6hUoUaHP72nCqY5Iibaa3eeiGBqIIU=\"' \\\n+https://api-accounts.dev.lcip.org/v1/account/device \\\n+-d '{\n+  \"id\": \"3d7d\",\n+  \"name\": \"My Old Phone\"\n+}'\n+```\n+\n+#### Response\n+\n+```\n+{\n+  \"id\": \"3d7d\",\n+  \"name\": \"My Phone\",\n+  \"type\": \"mobile\",\n+  \"callback\": \"https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef\"\n+}\n+```\n+\n+### POST /v1/account/create\n+\n+Authenticated with session token or OAuth.\n+\n+#### Requests\n+\n+##### New device\n+\n+```\n+curl -v \\\n+-X POST \\\n+-H \"Content-Type: application/json\" \\\n+\"https://api-accounts.dev.lcip.org/v1/account/create?keys=true\" \\\n+-d '{\n+  \"email\": \"me@example.com\",\n+  \"authPW\": \"996bc6b1aa63cd69856a2ec81cbf19d5c8a604713362df9ee15c2bf07128efab\",\n+  \"device\": {\n+    \"name\": \"My Phone\",\n+    \"type\": \"mobile\",\n+    \"callback\": \"https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef\"\n+  }\n+}'\n+```\n+\n+##### Registered device\n+\n+If a device id exists for this device,\n+the request MAY include it\n+but it MUST also include the other info as well,\n+since device ids are not globally unique.\n+\n+```\n+curl -v \\\n+-X POST \\\n+-H \"Content-Type: application/json\" \\\n+\"https://api-accounts.dev.lcip.org/v1/account/create?keys=true\" \\\n+-d '{\n+  \"email\": \"me@example.com\",\n+  \"authPW\": \"996bc6b1aa63cd69856a2ec81cbf19d5c8a604713362df9ee15c2bf07128efab\",\n+  \"device\": {\n+    \"id\": \"3d7d\",\n+    \"name\": \"My Phone\",\n+    \"type\": \"mobile\",\n+    \"callback\": \"https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef\"\n+  }\n+}'\n+```\n+\n+#### Response\n+\n+```\n+{\n+  \"uid\": \"4c352927cd4f4a4aa03d7d1893d950b8\",\n+  \"sessionToken\": \"27cd4f4a4aa03d7d186a2ec81cbf19d5c8a604713362df9ee15c4f4a4aa03d7d\",\n+  \"keyFetchToken\": \"7d1893d950b8cd69856a2ec81cbfd7d1893d950b3362df9e56a2ec81cbf19d5c\",\n+  \"authAt\": 1392144866,\n+  \"device\": {\n+    \"id\": \"3d7d\",\n+    \"name\": \"My Phone\",\n+    \"type\": \"mobile\",\n+    \"callback\": \"https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef\"\n+  }\n+}\n+```\n+\n+### POST /v1/account/device\n+\n+Authenticated with session token or OAuth.\n+\n+#### Requests\n+\n+##### New device\n+\n+```\n+curl -v \\\n+-X POST \\\n+-H \"Host: api-accounts.dev.lcip.org\" \\\n+-H \"Content-Type: application/json\" \\\n+-H 'Authorization: Hawk id=\"d4c5b1e3f5791ef83896c27519979b93a45e6d0da34c7509c5632ac35b28b48d\", ts=\"1373391043\", nonce=\"ohQjqb\", hash=\"vBODPWhDhiRWM4tmI9qp+np+3aoqEFzdGuGk0h7bh9w=\", mac=\"LAnpP3P2PXelC6hUoUaHP72nCqY5Iibaa3eeiGBqIIU=\"' \\\n+https://api-accounts.dev.lcip.org/v1/account/device \\\n+-d '{\n+  \"name\": \"My Phone\",","path":"features/FxA-45-device-registration-api/README.md","position":201,"original_position":188,"commit_id":"78f740c5c6c753d6731cdff2f7c818c3a758c903","original_commit_id":"eeaa48cdd843572382adf57ee2db6039751fe287","user":{"login":"rfk","id":34695,"avatar_url":"https://avatars.githubusercontent.com/u/34695?v=3","gravatar_id":"","url":"https://api.github.com/users/rfk","html_url":"https://github.com/rfk","followers_url":"https://api.github.com/users/rfk/followers","following_url":"https://api.github.com/users/rfk/following{/other_user}","gists_url":"https://api.github.com/users/rfk/gists{/gist_id}","starred_url":"https://api.github.com/users/rfk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rfk/subscriptions","organizations_url":"https://api.github.com/users/rfk/orgs","repos_url":"https://api.github.com/users/rfk/repos","events_url":"https://api.github.com/users/rfk/events{/privacy}","received_events_url":"https://api.github.com/users/rfk/received_events","type":"User","site_admin":false},"body":"I don't think we should enforce this, although we should try to generate unique names when we suggest defaults in the UI","created_at":"2015-10-29T04:52:20Z","updated_at":"2015-10-29T04:52:20Z","html_url":"https://github.com/mozilla/fxa/pull/69#discussion_r43348946","pull_request_url":"https://api.github.com/repos/mozilla/fxa/pulls/69","_links":{"self":{"href":"https://api.github.com/repos/mozilla/fxa/pulls/comments/43348946"},"html":{"href":"https://github.com/mozilla/fxa/pull/69#discussion_r43348946"},"pull_request":{"href":"https://api.github.com/repos/mozilla/fxa/pulls/69"}}},"pull_request":{"url":"https://api.github.com/repos/mozilla/fxa/pulls/69","id":48987411,"html_url":"https://github.com/mozilla/fxa/pull/69","diff_url":"https://github.com/mozilla/fxa/pull/69.diff","patch_url":"https://github.com/mozilla/fxa/pull/69.patch","issue_url":"https://api.github.com/repos/mozilla/fxa/issues/69","number":69,"state":"open","locked":false,"title":"feat(docs): first draft requirements for the device registration API","user":{"login":"philbooth","id":64367,"avatar_url":"https://avatars.githubusercontent.com/u/64367?v=3","gravatar_id":"","url":"https://api.github.com/users/philbooth","html_url":"https://github.com/philbooth","followers_url":"https://api.github.com/users/philbooth/followers","following_url":"https://api.github.com/users/philbooth/following{/other_user}","gists_url":"https://api.github.com/users/philbooth/gists{/gist_id}","starred_url":"https://api.github.com/users/philbooth/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/philbooth/subscriptions","organizations_url":"https://api.github.com/users/philbooth/orgs","repos_url":"https://api.github.com/users/philbooth/repos","events_url":"https://api.github.com/users/philbooth/events{/privacy}","received_events_url":"https://api.github.com/users/philbooth/received_events","type":"User","site_admin":false},"body":"I cobbled this together for discussion, based on the approach taken in #66 and the information in Danny's gist. Hopefully it's a starting point from which to nail down the details of the device registration API.\r\n\r\n@shane-tomlinson @rfk r?","created_at":"2015-10-28T10:29:19Z","updated_at":"2015-10-29T04:52:20Z","closed_at":null,"merged_at":null,"merge_commit_sha":"d3e78b9cdd114c7b879b1f1da29eaa1313fdd142","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/mozilla/fxa/pulls/69/commits","review_comments_url":"https://api.github.com/repos/mozilla/fxa/pulls/69/comments","review_comment_url":"https://api.github.com/repos/mozilla/fxa/pulls/comments{/number}","comments_url":"https://api.github.com/repos/mozilla/fxa/issues/69/comments","statuses_url":"https://api.github.com/repos/mozilla/fxa/statuses/78f740c5c6c753d6731cdff2f7c818c3a758c903","head":{"label":"mozilla:phil/fxa-45-requirements","ref":"phil/fxa-45-requirements","sha":"78f740c5c6c753d6731cdff2f7c818c3a758c903","user":{"login":"mozilla","id":131524,"avatar_url":"https://avatars.githubusercontent.com/u/131524?v=3","gravatar_id":"","url":"https://api.github.com/users/mozilla","html_url":"https://github.com/mozilla","followers_url":"https://api.github.com/users/mozilla/followers","following_url":"https://api.github.com/users/mozilla/following{/other_user}","gists_url":"https://api.github.com/users/mozilla/gists{/gist_id}","starred_url":"https://api.github.com/users/mozilla/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mozilla/subscriptions","organizations_url":"https://api.github.com/users/mozilla/orgs","repos_url":"https://api.github.com/users/mozilla/repos","events_url":"https://api.github.com/users/mozilla/events{/privacy}","received_events_url":"https://api.github.com/users/mozilla/received_events","type":"Organization","site_admin":false},"repo":{"id":36831081,"name":"fxa","full_name":"mozilla/fxa","owner":{"login":"mozilla","id":131524,"avatar_url":"https://avatars.githubusercontent.com/u/131524?v=3","gravatar_id":"","url":"https://api.github.com/users/mozilla","html_url":"https://github.com/mozilla","followers_url":"https://api.github.com/users/mozilla/followers","following_url":"https://api.github.com/users/mozilla/following{/other_user}","gists_url":"https://api.github.com/users/mozilla/gists{/gist_id}","starred_url":"https://api.github.com/users/mozilla/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mozilla/subscriptions","organizations_url":"https://api.github.com/users/mozilla/orgs","repos_url":"https://api.github.com/users/mozilla/repos","events_url":"https://api.github.com/users/mozilla/events{/privacy}","received_events_url":"https://api.github.com/users/mozilla/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/mozilla/fxa","description":"Top-level repository for Firefox Accounts","fork":false,"url":"https://api.github.com/repos/mozilla/fxa","forks_url":"https://api.github.com/repos/mozilla/fxa/forks","keys_url":"https://api.github.com/repos/mozilla/fxa/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mozilla/fxa/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mozilla/fxa/teams","hooks_url":"https://api.github.com/repos/mozilla/fxa/hooks","issue_events_url":"https://api.github.com/repos/mozilla/fxa/issues/events{/number}","events_url":"https://api.github.com/repos/mozilla/fxa/events","assignees_url":"https://api.github.com/repos/mozilla/fxa/assignees{/user}","branches_url":"https://api.github.com/repos/mozilla/fxa/branches{/branch}","tags_url":"https://api.github.com/repos/mozilla/fxa/tags","blobs_url":"https://api.github.com/repos/mozilla/fxa/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mozilla/fxa/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mozilla/fxa/git/refs{/sha}","trees_url":"https://api.github.com/repos/mozilla/fxa/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mozilla/fxa/statuses/{sha}","languages_url":"https://api.github.com/repos/mozilla/fxa/languages","stargazers_url":"https://api.github.com/repos/mozilla/fxa/stargazers","contributors_url":"https://api.github.com/repos/mozilla/fxa/contributors","subscribers_url":"https://api.github.com/repos/mozilla/fxa/subscribers","subscription_url":"https://api.github.com/repos/mozilla/fxa/subscription","commits_url":"https://api.github.com/repos/mozilla/fxa/commits{/sha}","git_commits_url":"https://api.github.com/repos/mozilla/fxa/git/commits{/sha}","comments_url":"https://api.github.com/repos/mozilla/fxa/comments{/number}","issue_comment_url":"https://api.github.com/repos/mozilla/fxa/issues/comments{/number}","contents_url":"https://api.github.com/repos/mozilla/fxa/contents/{+path}","compare_url":"https://api.github.com/repos/mozilla/fxa/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mozilla/fxa/merges","archive_url":"https://api.github.com/repos/mozilla/fxa/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mozilla/fxa/downloads","issues_url":"https://api.github.com/repos/mozilla/fxa/issues{/number}","pulls_url":"https://api.github.com/repos/mozilla/fxa/pulls{/number}","milestones_url":"https://api.github.com/repos/mozilla/fxa/milestones{/number}","notifications_url":"https://api.github.com/repos/mozilla/fxa/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mozilla/fxa/labels{/name}","releases_url":"https://api.github.com/repos/mozilla/fxa/releases{/id}","created_at":"2015-06-03T21:16:46Z","updated_at":"2015-10-24T16:37:07Z","pushed_at":"2015-10-28T19:38:23Z","git_url":"git://github.com/mozilla/fxa.git","ssh_url":"git@github.com:mozilla/fxa.git","clone_url":"https://github.com/mozilla/fxa.git","svn_url":"https://github.com/mozilla/fxa","homepage":"http://fxa.readthedocs.org","size":1867,"stargazers_count":4,"watchers_count":4,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":5,"mirror_url":null,"open_issues_count":12,"forks":5,"open_issues":12,"watchers":4,"default_branch":"master"}},"base":{"label":"mozilla:master","ref":"master","sha":"39ec152ede28340f7e8b430478eb1d959f67a569","user":{"login":"mozilla","id":131524,"avatar_url":"https://avatars.githubusercontent.com/u/131524?v=3","gravatar_id":"","url":"https://api.github.com/users/mozilla","html_url":"https://github.com/mozilla","followers_url":"https://api.github.com/users/mozilla/followers","following_url":"https://api.github.com/users/mozilla/following{/other_user}","gists_url":"https://api.github.com/users/mozilla/gists{/gist_id}","starred_url":"https://api.github.com/users/mozilla/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mozilla/subscriptions","organizations_url":"https://api.github.com/users/mozilla/orgs","repos_url":"https://api.github.com/users/mozilla/repos","events_url":"https://api.github.com/users/mozilla/events{/privacy}","received_events_url":"https://api.github.com/users/mozilla/received_events","type":"Organization","site_admin":false},"repo":{"id":36831081,"name":"fxa","full_name":"mozilla/fxa","owner":{"login":"mozilla","id":131524,"avatar_url":"https://avatars.githubusercontent.com/u/131524?v=3","gravatar_id":"","url":"https://api.github.com/users/mozilla","html_url":"https://github.com/mozilla","followers_url":"https://api.github.com/users/mozilla/followers","following_url":"https://api.github.com/users/mozilla/following{/other_user}","gists_url":"https://api.github.com/users/mozilla/gists{/gist_id}","starred_url":"https://api.github.com/users/mozilla/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mozilla/subscriptions","organizations_url":"https://api.github.com/users/mozilla/orgs","repos_url":"https://api.github.com/users/mozilla/repos","events_url":"https://api.github.com/users/mozilla/events{/privacy}","received_events_url":"https://api.github.com/users/mozilla/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/mozilla/fxa","description":"Top-level repository for Firefox Accounts","fork":false,"url":"https://api.github.com/repos/mozilla/fxa","forks_url":"https://api.github.com/repos/mozilla/fxa/forks","keys_url":"https://api.github.com/repos/mozilla/fxa/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mozilla/fxa/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mozilla/fxa/teams","hooks_url":"https://api.github.com/repos/mozilla/fxa/hooks","issue_events_url":"https://api.github.com/repos/mozilla/fxa/issues/events{/number}","events_url":"https://api.github.com/repos/mozilla/fxa/events","assignees_url":"https://api.github.com/repos/mozilla/fxa/assignees{/user}","branches_url":"https://api.github.com/repos/mozilla/fxa/branches{/branch}","tags_url":"https://api.github.com/repos/mozilla/fxa/tags","blobs_url":"https://api.github.com/repos/mozilla/fxa/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mozilla/fxa/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mozilla/fxa/git/refs{/sha}","trees_url":"https://api.github.com/repos/mozilla/fxa/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mozilla/fxa/statuses/{sha}","languages_url":"https://api.github.com/repos/mozilla/fxa/languages","stargazers_url":"https://api.github.com/repos/mozilla/fxa/stargazers","contributors_url":"https://api.github.com/repos/mozilla/fxa/contributors","subscribers_url":"https://api.github.com/repos/mozilla/fxa/subscribers","subscription_url":"https://api.github.com/repos/mozilla/fxa/subscription","commits_url":"https://api.github.com/repos/mozilla/fxa/commits{/sha}","git_commits_url":"https://api.github.com/repos/mozilla/fxa/git/commits{/sha}","comments_url":"https://api.github.com/repos/mozilla/fxa/comments{/number}","issue_comment_url":"https://api.github.com/repos/mozilla/fxa/issues/comments{/number}","contents_url":"https://api.github.com/repos/mozilla/fxa/contents/{+path}","compare_url":"https://api.github.com/repos/mozilla/fxa/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mozilla/fxa/merges","archive_url":"https://api.github.com/repos/mozilla/fxa/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mozilla/fxa/downloads","issues_url":"https://api.github.com/repos/mozilla/fxa/issues{/number}","pulls_url":"https://api.github.com/repos/mozilla/fxa/pulls{/number}","milestones_url":"https://api.github.com/repos/mozilla/fxa/milestones{/number}","notifications_url":"https://api.github.com/repos/mozilla/fxa/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mozilla/fxa/labels{/name}","releases_url":"https://api.github.com/repos/mozilla/fxa/releases{/id}","created_at":"2015-06-03T21:16:46Z","updated_at":"2015-10-24T16:37:07Z","pushed_at":"2015-10-28T19:38:23Z","git_url":"git://github.com/mozilla/fxa.git","ssh_url":"git@github.com:mozilla/fxa.git","clone_url":"https://github.com/mozilla/fxa.git","svn_url":"https://github.com/mozilla/fxa","homepage":"http://fxa.readthedocs.org","size":1867,"stargazers_count":4,"watchers_count":4,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":5,"mirror_url":null,"open_issues_count":12,"forks":5,"open_issues":12,"watchers":4,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/mozilla/fxa/pulls/69"},"html":{"href":"https://github.com/mozilla/fxa/pull/69"},"issue":{"href":"https://api.github.com/repos/mozilla/fxa/issues/69"},"comments":{"href":"https://api.github.com/repos/mozilla/fxa/issues/69/comments"},"review_comments":{"href":"https://api.github.com/repos/mozilla/fxa/pulls/69/comments"},"review_comment":{"href":"https://api.github.com/repos/mozilla/fxa/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/mozilla/fxa/pulls/69/commits"},"statuses":{"href":"https://api.github.com/repos/mozilla/fxa/statuses/78f740c5c6c753d6731cdff2f7c818c3a758c903"}}}}