{"action":"created","comment":{"url":"https://api.github.com/repos/diaspora/api-documentation/pulls/comments/238243686","pull_request_review_id":180734979,"id":238243686,"node_id":"MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDIzODI0MzY4Ng==","diff_hunk":"@@ -0,0 +1,138 @@\n+---\n+title: Access scopes\n+---\n+\n+diaspora* API features access scopes (or just 'scopes') in order to implement resource access management for API clients.\n+\n+Scopes are part of [OAuth 2.0 specification][oauth2] which is a base for [OpenID Connect Core 1.0][connect] implemented by diaspora*.\n+\n+When the API client requests an access token it sends the list of scopes it wants to get access to accoring to the selected authorization flow (see [\"Authentication\"][authentication]).\n+\n+Approved scopes may differ from what was requested by the client.\n+\n+[OpenID Connect Core 1.0][connect] defines a few scopes which are specific for getting the authorized user information. API client must include the `openid` scope to the scope request list. `openid` scope means \"allow OpenID Connect authentication\" and if missing then API authentication will fail.\n+\n+diaspora* also supports `profile` and `email` scopes according to [OpenID Connect Core 1.0][connect-scopes].\n+\n+Other scopes are diaspora* API specific. All scopes besides `openid` are optional.\n+\n+Each API endpoint requires at least one scope to be approved. If the access token used for making a request wasn't approved for the scope of the respective endpoint then `403` status will be responded.\n+\n+## Scopes list\n+\n+### contacts:read\n+\n+This scope gives access to the following requests:\n+- Read aspect list\n+- Read aspects membership\n+- Read private user profiles of contacts\n+- Read contacts of contacts when allowed by contact's aspect setting\n+- User search will include contacts who are hidden from public search\n+\n+### contacts:modify\n+\n+This scope gives access to the following requests:\n+- Add new aspects\n+- Rename aspects and change aspects properties\n+- Delete aspects\n+- Add/remove person to/from aspects\n+\n+### conversations\n+\n+This scope gives access to private messaging, i.e. the following requests:\n+- Create conversations\n+- Send private messages\n+\n+### email\n+\n+This scope is defined by the OpenID Connect spec. It allows reading user's own email address using UserInfo route or from ID Token.\n+\n+### interactions\n+\n+This scope gives access to the following requests:\n+- Create/delete comments\n+- Report posts/comments\n+- Post/remove likes\n+- Subscribe/mute posts\n+- Hide posts from streams\n+\n+### openid\n+\n+This scope is defined by the OpenID Connect spec. This is a mandatory scope. It gives access to OpenID Connect authentication.\n+\n+### private\n+\n+This scope gives access to the following requests:\n+- Read private posts\n+- Read private posts intercations (likes, comments)\n+\n+Reading private posts of contacts additionaly requires `contacts:read` scope.\n+\n+### public\n+\n+This scope gives access to the following requests:\n+- Read public profiles of users\n+- Perform search among publicly searchable profiles\n+- Read public posts\n+- Read reshares\n+- Read public posts intercations (likes, comments)\n+\n+### posts:publish\n+\n+This scope gives access to the following requests:\n+- Create posts\n+- Create reshares\n+- Post photos\n+\n+Create private posts additionaly requires `contacts:read` scope.\n+\n+### posts:modify\n+\n+This scope gives access to the following requests:\n+- Delete posts\n+- Delete photos\n+\n+### profile\n+\n+This scope is defined by the OpenID Connect spec. It allows reading user claims (user properties). Claims are read using UserInfo route or from ID Token.\n+\n+User claims defined by the OpenID Connect are somewhat similar to users own profile data. Generally this scope means \"Allow reading user's own profile\". Besides user claims defined by the standard this scope also gives access to \"read own profile\" diaspora* API endpoint.\n+\n+Supported claims by diaspora:\n+\n+| claim      | meaning                                             |\n+| ---------- | --------------------------------------------------- |\n+| name       | Full name                                           |\n+| nickname   | The left part of diaspora handle before `@` sign    |\n+| profile    | User's profile URL address                          |\n+| picture    | User avatar URL address                             |\n+| gender     | Gender profile field                                |\n+| birthdate  | Birth date profile field                            |\n+| locale     | UI language selection specified in account settings |\n+| updated_at | Date of last profile edit                           |\n+\n+### profile:modify\n+\n+This scope gives access to updating users own profile\n+\n+### tags\n+\n+This scope gives access to read/create/delete tag followings.\n+\n+### streams\n+\n+This scope gives access streams.\n+\n+There are 3 types of streams available. Accessing each stream requires two scopes: `streams` scope and a scope specific for the stream type.\n+\n+| Stream name     | Stream specifics                           | Access scopes               |\n+| --------------- | ------------------------------------------ | --------------------------- |\n+| Activity stream | Includes posts with users own activity     | `streams` + `interactions`  |","path":"scopes.md","position":130,"original_position":130,"commit_id":"5bbd703816afafab4077f19ca4f0fc35bf5c78ac","original_commit_id":"4d2f4c6b7a6a4ad3f65d85b4a8dee218f6c28acb","user":{"login":"cmrd-senya","id":10187586,"node_id":"MDQ6VXNlcjEwMTg3NTg2","avatar_url":"https://avatars2.githubusercontent.com/u/10187586?v=4","gravatar_id":"","url":"https://api.github.com/users/cmrd-senya","html_url":"https://github.com/cmrd-senya","followers_url":"https://api.github.com/users/cmrd-senya/followers","following_url":"https://api.github.com/users/cmrd-senya/following{/other_user}","gists_url":"https://api.github.com/users/cmrd-senya/gists{/gist_id}","starred_url":"https://api.github.com/users/cmrd-senya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cmrd-senya/subscriptions","organizations_url":"https://api.github.com/users/cmrd-senya/orgs","repos_url":"https://api.github.com/users/cmrd-senya/repos","events_url":"https://api.github.com/users/cmrd-senya/events{/privacy}","received_events_url":"https://api.github.com/users/cmrd-senya/received_events","type":"User","site_admin":false},"body":"However above in the document we state that `public` is required to access public posts and `private` is required to access private posts. Technically it means that we can grant access to private posts only or public posts only. If we don't want this public/private only access then we probably should redefine these `public` and `private` scopes too. For instance we could define a scope for accessing posts (public and your own private) and which will also grant access to your friends posts when combined with `contacts:read`.","created_at":"2018-12-03T12:09:46Z","updated_at":"2018-12-03T12:09:47Z","html_url":"https://github.com/diaspora/api-documentation/pull/12#discussion_r238243686","pull_request_url":"https://api.github.com/repos/diaspora/api-documentation/pulls/12","author_association":"MEMBER","_links":{"self":{"href":"https://api.github.com/repos/diaspora/api-documentation/pulls/comments/238243686"},"html":{"href":"https://github.com/diaspora/api-documentation/pull/12#discussion_r238243686"},"pull_request":{"href":"https://api.github.com/repos/diaspora/api-documentation/pulls/12"}},"in_reply_to_id":237470189},"pull_request":{"url":"https://api.github.com/repos/diaspora/api-documentation/pulls/12","id":199793049,"node_id":"MDExOlB1bGxSZXF1ZXN0MTk5NzkzMDQ5","html_url":"https://github.com/diaspora/api-documentation/pull/12","diff_url":"https://github.com/diaspora/api-documentation/pull/12.diff","patch_url":"https://github.com/diaspora/api-documentation/pull/12.patch","issue_url":"https://api.github.com/repos/diaspora/api-documentation/issues/12","number":12,"state":"open","locked":false,"title":"Describe access scopes","user":{"login":"cmrd-senya","id":10187586,"node_id":"MDQ6VXNlcjEwMTg3NTg2","avatar_url":"https://avatars2.githubusercontent.com/u/10187586?v=4","gravatar_id":"","url":"https://api.github.com/users/cmrd-senya","html_url":"https://github.com/cmrd-senya","followers_url":"https://api.github.com/users/cmrd-senya/followers","following_url":"https://api.github.com/users/cmrd-senya/following{/other_user}","gists_url":"https://api.github.com/users/cmrd-senya/gists{/gist_id}","starred_url":"https://api.github.com/users/cmrd-senya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cmrd-senya/subscriptions","organizations_url":"https://api.github.com/users/cmrd-senya/orgs","repos_url":"https://api.github.com/users/cmrd-senya/repos","events_url":"https://api.github.com/users/cmrd-senya/events{/privacy}","received_events_url":"https://api.github.com/users/cmrd-senya/received_events","type":"User","site_admin":false},"body":"fixes #3 \r\n\r\nThis is preliminary description of access scopes.\r\n\r\nTODO:\r\n- [ ] Add scopes info to `authentication` page and correct scopes and claims in examples\r\n- [ ] Add required scopes  to each listed route","created_at":"2018-07-06T16:26:05Z","updated_at":"2018-12-03T12:09:47Z","closed_at":null,"merged_at":null,"merge_commit_sha":"06de3e6ef41a7e9d0fc726949e9a0bb0d5ccc5f7","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/diaspora/api-documentation/pulls/12/commits","review_comments_url":"https://api.github.com/repos/diaspora/api-documentation/pulls/12/comments","review_comment_url":"https://api.github.com/repos/diaspora/api-documentation/pulls/comments{/number}","comments_url":"https://api.github.com/repos/diaspora/api-documentation/issues/12/comments","statuses_url":"https://api.github.com/repos/diaspora/api-documentation/statuses/5bbd703816afafab4077f19ca4f0fc35bf5c78ac","head":{"label":"cmrd-senya:scopes","ref":"scopes","sha":"5bbd703816afafab4077f19ca4f0fc35bf5c78ac","user":{"login":"cmrd-senya","id":10187586,"node_id":"MDQ6VXNlcjEwMTg3NTg2","avatar_url":"https://avatars2.githubusercontent.com/u/10187586?v=4","gravatar_id":"","url":"https://api.github.com/users/cmrd-senya","html_url":"https://github.com/cmrd-senya","followers_url":"https://api.github.com/users/cmrd-senya/followers","following_url":"https://api.github.com/users/cmrd-senya/following{/other_user}","gists_url":"https://api.github.com/users/cmrd-senya/gists{/gist_id}","starred_url":"https://api.github.com/users/cmrd-senya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cmrd-senya/subscriptions","organizations_url":"https://api.github.com/users/cmrd-senya/orgs","repos_url":"https://api.github.com/users/cmrd-senya/repos","events_url":"https://api.github.com/users/cmrd-senya/events{/privacy}","received_events_url":"https://api.github.com/users/cmrd-senya/received_events","type":"User","site_admin":false},"repo":{"id":123615710,"node_id":"MDEwOlJlcG9zaXRvcnkxMjM2MTU3MTA=","name":"api-documentation","full_name":"cmrd-senya/api-documentation","private":false,"owner":{"login":"cmrd-senya","id":10187586,"node_id":"MDQ6VXNlcjEwMTg3NTg2","avatar_url":"https://avatars2.githubusercontent.com/u/10187586?v=4","gravatar_id":"","url":"https://api.github.com/users/cmrd-senya","html_url":"https://github.com/cmrd-senya","followers_url":"https://api.github.com/users/cmrd-senya/followers","following_url":"https://api.github.com/users/cmrd-senya/following{/other_user}","gists_url":"https://api.github.com/users/cmrd-senya/gists{/gist_id}","starred_url":"https://api.github.com/users/cmrd-senya/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cmrd-senya/subscriptions","organizations_url":"https://api.github.com/users/cmrd-senya/orgs","repos_url":"https://api.github.com/users/cmrd-senya/repos","events_url":"https://api.github.com/users/cmrd-senya/events{/privacy}","received_events_url":"https://api.github.com/users/cmrd-senya/received_events","type":"User","site_admin":false},"html_url":"https://github.com/cmrd-senya/api-documentation","description":"diaspora*s API documentation","fork":true,"url":"https://api.github.com/repos/cmrd-senya/api-documentation","forks_url":"https://api.github.com/repos/cmrd-senya/api-documentation/forks","keys_url":"https://api.github.com/repos/cmrd-senya/api-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/cmrd-senya/api-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/cmrd-senya/api-documentation/teams","hooks_url":"https://api.github.com/repos/cmrd-senya/api-documentation/hooks","issue_events_url":"https://api.github.com/repos/cmrd-senya/api-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/cmrd-senya/api-documentation/events","assignees_url":"https://api.github.com/repos/cmrd-senya/api-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/cmrd-senya/api-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/cmrd-senya/api-documentation/tags","blobs_url":"https://api.github.com/repos/cmrd-senya/api-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/cmrd-senya/api-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/cmrd-senya/api-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/cmrd-senya/api-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/cmrd-senya/api-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/cmrd-senya/api-documentation/languages","stargazers_url":"https://api.github.com/repos/cmrd-senya/api-documentation/stargazers","contributors_url":"https://api.github.com/repos/cmrd-senya/api-documentation/contributors","subscribers_url":"https://api.github.com/repos/cmrd-senya/api-documentation/subscribers","subscription_url":"https://api.github.com/repos/cmrd-senya/api-documentation/subscription","commits_url":"https://api.github.com/repos/cmrd-senya/api-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/cmrd-senya/api-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/cmrd-senya/api-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/cmrd-senya/api-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/cmrd-senya/api-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/cmrd-senya/api-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/cmrd-senya/api-documentation/merges","archive_url":"https://api.github.com/repos/cmrd-senya/api-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/cmrd-senya/api-documentation/downloads","issues_url":"https://api.github.com/repos/cmrd-senya/api-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/cmrd-senya/api-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/cmrd-senya/api-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/cmrd-senya/api-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/cmrd-senya/api-documentation/labels{/name}","releases_url":"https://api.github.com/repos/cmrd-senya/api-documentation/releases{/id}","deployments_url":"https://api.github.com/repos/cmrd-senya/api-documentation/deployments","created_at":"2018-03-02T18:30:03Z","updated_at":"2018-03-02T18:30:05Z","pushed_at":"2018-12-03T10:57:12Z","git_url":"git://github.com/cmrd-senya/api-documentation.git","ssh_url":"git@github.com:cmrd-senya/api-documentation.git","clone_url":"https://github.com/cmrd-senya/api-documentation.git","svn_url":"https://github.com/cmrd-senya/api-documentation","homepage":"https://diaspora.github.io/api-documentation/","size":2994,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":{"key":"cc-by-sa-4.0","name":"Creative Commons Attribution Share Alike 4.0 International","spdx_id":"CC-BY-SA-4.0","url":"https://api.github.com/licenses/cc-by-sa-4.0","node_id":"MDc6TGljZW5zZTI2"},"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"diaspora:master","ref":"master","sha":"d6745ac1149d548ece199d1cacec303669874288","user":{"login":"diaspora","id":293207,"node_id":"MDEyOk9yZ2FuaXphdGlvbjI5MzIwNw==","avatar_url":"https://avatars3.githubusercontent.com/u/293207?v=4","gravatar_id":"","url":"https://api.github.com/users/diaspora","html_url":"https://github.com/diaspora","followers_url":"https://api.github.com/users/diaspora/followers","following_url":"https://api.github.com/users/diaspora/following{/other_user}","gists_url":"https://api.github.com/users/diaspora/gists{/gist_id}","starred_url":"https://api.github.com/users/diaspora/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/diaspora/subscriptions","organizations_url":"https://api.github.com/users/diaspora/orgs","repos_url":"https://api.github.com/users/diaspora/repos","events_url":"https://api.github.com/users/diaspora/events{/privacy}","received_events_url":"https://api.github.com/users/diaspora/received_events","type":"Organization","site_admin":false},"repo":{"id":51509191,"node_id":"MDEwOlJlcG9zaXRvcnk1MTUwOTE5MQ==","name":"api-documentation","full_name":"diaspora/api-documentation","private":false,"owner":{"login":"diaspora","id":293207,"node_id":"MDEyOk9yZ2FuaXphdGlvbjI5MzIwNw==","avatar_url":"https://avatars3.githubusercontent.com/u/293207?v=4","gravatar_id":"","url":"https://api.github.com/users/diaspora","html_url":"https://github.com/diaspora","followers_url":"https://api.github.com/users/diaspora/followers","following_url":"https://api.github.com/users/diaspora/following{/other_user}","gists_url":"https://api.github.com/users/diaspora/gists{/gist_id}","starred_url":"https://api.github.com/users/diaspora/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/diaspora/subscriptions","organizations_url":"https://api.github.com/users/diaspora/orgs","repos_url":"https://api.github.com/users/diaspora/repos","events_url":"https://api.github.com/users/diaspora/events{/privacy}","received_events_url":"https://api.github.com/users/diaspora/received_events","type":"Organization","site_admin":false},"html_url":"https://github.com/diaspora/api-documentation","description":"diaspora*s API documentation","fork":false,"url":"https://api.github.com/repos/diaspora/api-documentation","forks_url":"https://api.github.com/repos/diaspora/api-documentation/forks","keys_url":"https://api.github.com/repos/diaspora/api-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/diaspora/api-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/diaspora/api-documentation/teams","hooks_url":"https://api.github.com/repos/diaspora/api-documentation/hooks","issue_events_url":"https://api.github.com/repos/diaspora/api-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/diaspora/api-documentation/events","assignees_url":"https://api.github.com/repos/diaspora/api-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/diaspora/api-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/diaspora/api-documentation/tags","blobs_url":"https://api.github.com/repos/diaspora/api-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/diaspora/api-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/diaspora/api-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/diaspora/api-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/diaspora/api-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/diaspora/api-documentation/languages","stargazers_url":"https://api.github.com/repos/diaspora/api-documentation/stargazers","contributors_url":"https://api.github.com/repos/diaspora/api-documentation/contributors","subscribers_url":"https://api.github.com/repos/diaspora/api-documentation/subscribers","subscription_url":"https://api.github.com/repos/diaspora/api-documentation/subscription","commits_url":"https://api.github.com/repos/diaspora/api-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/diaspora/api-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/diaspora/api-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/diaspora/api-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/diaspora/api-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/diaspora/api-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/diaspora/api-documentation/merges","archive_url":"https://api.github.com/repos/diaspora/api-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/diaspora/api-documentation/downloads","issues_url":"https://api.github.com/repos/diaspora/api-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/diaspora/api-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/diaspora/api-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/diaspora/api-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/diaspora/api-documentation/labels{/name}","releases_url":"https://api.github.com/repos/diaspora/api-documentation/releases{/id}","deployments_url":"https://api.github.com/repos/diaspora/api-documentation/deployments","created_at":"2016-02-11T10:59:05Z","updated_at":"2018-10-21T00:33:03Z","pushed_at":"2018-12-03T10:57:14Z","git_url":"git://github.com/diaspora/api-documentation.git","ssh_url":"git@github.com:diaspora/api-documentation.git","clone_url":"https://github.com/diaspora/api-documentation.git","svn_url":"https://github.com/diaspora/api-documentation","homepage":"https://diaspora.github.io/api-documentation/","size":2993,"stargazers_count":11,"watchers_count":11,"language":"CSS","has_issues":true,"has_projects":false,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":8,"mirror_url":null,"archived":false,"open_issues_count":17,"license":{"key":"cc-by-sa-4.0","name":"Creative Commons Attribution Share Alike 4.0 International","spdx_id":"CC-BY-SA-4.0","url":"https://api.github.com/licenses/cc-by-sa-4.0","node_id":"MDc6TGljZW5zZTI2"},"forks":8,"open_issues":17,"watchers":11,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/diaspora/api-documentation/pulls/12"},"html":{"href":"https://github.com/diaspora/api-documentation/pull/12"},"issue":{"href":"https://api.github.com/repos/diaspora/api-documentation/issues/12"},"comments":{"href":"https://api.github.com/repos/diaspora/api-documentation/issues/12/comments"},"review_comments":{"href":"https://api.github.com/repos/diaspora/api-documentation/pulls/12/comments"},"review_comment":{"href":"https://api.github.com/repos/diaspora/api-documentation/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/diaspora/api-documentation/pulls/12/commits"},"statuses":{"href":"https://api.github.com/repos/diaspora/api-documentation/statuses/5bbd703816afafab4077f19ca4f0fc35bf5c78ac"}},"author_association":"MEMBER"}}
{"actor":{"display_login":"cmrd-senya"}}