{"action":"created","comment":{"url":"https://api.github.com/repos/opf/openproject/pulls/comments/28127391","id":28127391,"diff_hunk":"@@ -40,11 +40,42 @@ in the [Collections Section](#collections).\n \n # Authentication\n \n-For now the API only supports **session-based authentication**. This means you have to login to OpenProject via\n-the Web-Interface to be authenticated in the API. This method is well-suited for clients acting within the browser,\n-like the Angular-Client built into OpenProject.\n+For now the API only supports two authentication schemes: session based authentication and basic auth.\n \n-However for the future we plan to add authentication modes that are more suitable for **external clients** too.\n+## Session-based Authentication\n+\n+This means you have to login to OpenProject via the Web-Interface to be authenticated in the API.\n+This method is well-suited for clients acting within the browser, like the Angular-Client built into OpenProject.\n+\n+## API Key through Basic Auth\n+\n+Users can authenticate towards the API v3 using basic auth with 'apikey' as the user name and their API key as the password. Users can find their API key on their account page.\n+\n+Example:\n+\n+```bash\n+API_KEY=2519132cdf62dcf5a66fd96394672079f9e9cad1\n+curl -u apikey:$API_KEY https://community.openproject.com/api/v3/users/42\n+```\n+\n+### Why not username and password?\n+\n+The simplest way to do basic auth would be to use a user's username and password naturally.\n+However, OpenProject already has supported API keys in the past for the API v2, though not through basic auth.\n+\n+Using **username and password** directly would have some advantages:\n+\n+* It is intuitive for the user who then just has to provide those just as they would when logging into OpenProject.\n+* No extra logic for token managment necessary.\n+\n+On the other hand using **API keys* has some advantages too, which is why we went for them:","path":"doc/apiv3-documentation.apib","position":36,"original_position":36,"commit_id":"23eeb171f777b0bb8b774043cdbd687a58362a86","original_commit_id":"23eeb171f777b0bb8b774043cdbd687a58362a86","user":{"login":"NobodysNightmare","id":453584,"avatar_url":"https://avatars.githubusercontent.com/u/453584?v=3","gravatar_id":"","url":"https://api.github.com/users/NobodysNightmare","html_url":"https://github.com/NobodysNightmare","followers_url":"https://api.github.com/users/NobodysNightmare/followers","following_url":"https://api.github.com/users/NobodysNightmare/following{/other_user}","gists_url":"https://api.github.com/users/NobodysNightmare/gists{/gist_id}","starred_url":"https://api.github.com/users/NobodysNightmare/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/NobodysNightmare/subscriptions","organizations_url":"https://api.github.com/users/NobodysNightmare/orgs","repos_url":"https://api.github.com/users/NobodysNightmare/repos","events_url":"https://api.github.com/users/NobodysNightmare/events{/privacy}","received_events_url":"https://api.github.com/users/NobodysNightmare/received_events","type":"User","site_admin":false},"body":"broken formatting, two stars before `API keys`, one after.","created_at":"2015-04-10T07:55:41Z","updated_at":"2015-04-10T07:55:41Z","html_url":"https://github.com/opf/openproject/pull/2807#discussion_r28127391","pull_request_url":"https://api.github.com/repos/opf/openproject/pulls/2807","_links":{"self":{"href":"https://api.github.com/repos/opf/openproject/pulls/comments/28127391"},"html":{"href":"https://github.com/opf/openproject/pull/2807#discussion_r28127391"},"pull_request":{"href":"https://api.github.com/repos/opf/openproject/pulls/2807"}}},"pull_request":{"url":"https://api.github.com/repos/opf/openproject/pulls/2807","id":33024893,"html_url":"https://github.com/opf/openproject/pull/2807","diff_url":"https://github.com/opf/openproject/pull/2807.diff","patch_url":"https://github.com/opf/openproject/pull/2807.patch","issue_url":"https://api.github.com/repos/opf/openproject/issues/2807","number":2807,"state":"open","locked":false,"title":"API v3 basic auth API doc","user":{"login":"machisuji","id":158871,"avatar_url":"https://avatars.githubusercontent.com/u/158871?v=3","gravatar_id":"","url":"https://api.github.com/users/machisuji","html_url":"https://github.com/machisuji","followers_url":"https://api.github.com/users/machisuji/followers","following_url":"https://api.github.com/users/machisuji/following{/other_user}","gists_url":"https://api.github.com/users/machisuji/gists{/gist_id}","starred_url":"https://api.github.com/users/machisuji/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/machisuji/subscriptions","organizations_url":"https://api.github.com/users/machisuji/orgs","repos_url":"https://api.github.com/users/machisuji/repos","events_url":"https://api.github.com/users/machisuji/events{/privacy}","received_events_url":"https://api.github.com/users/machisuji/received_events","type":"User","site_admin":false},"body":"Proposal for basic auth for API v3. Contains only the documentation.\r\n\r\nOpen for discussion (/cc @opf/developers). Not intended for the 4.1 release, but would be nice for 4.2.\r\n\r\nWP [#19294](https://community.openproject.org/work_packages/19294)\r\n\r\nThe argument about what to use is directly in the documentation currently.","created_at":"2015-04-10T07:49:19Z","updated_at":"2015-04-10T07:55:41Z","closed_at":null,"merged_at":null,"merge_commit_sha":"52aa200464f8eb804522c8786cb7fc330b1f6f85","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/opf/openproject/pulls/2807/commits","review_comments_url":"https://api.github.com/repos/opf/openproject/pulls/2807/comments","review_comment_url":"https://api.github.com/repos/opf/openproject/pulls/comments{/number}","comments_url":"https://api.github.com/repos/opf/openproject/issues/2807/comments","statuses_url":"https://api.github.com/repos/opf/openproject/statuses/23eeb171f777b0bb8b774043cdbd687a58362a86","head":{"label":"machisuji:feature/api_v3_basic_auth_api_doc","ref":"feature/api_v3_basic_auth_api_doc","sha":"23eeb171f777b0bb8b774043cdbd687a58362a86","user":{"login":"machisuji","id":158871,"avatar_url":"https://avatars.githubusercontent.com/u/158871?v=3","gravatar_id":"","url":"https://api.github.com/users/machisuji","html_url":"https://github.com/machisuji","followers_url":"https://api.github.com/users/machisuji/followers","following_url":"https://api.github.com/users/machisuji/following{/other_user}","gists_url":"https://api.github.com/users/machisuji/gists{/gist_id}","starred_url":"https://api.github.com/users/machisuji/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/machisuji/subscriptions","organizations_url":"https://api.github.com/users/machisuji/orgs","repos_url":"https://api.github.com/users/machisuji/repos","events_url":"https://api.github.com/users/machisuji/events{/privacy}","received_events_url":"https://api.github.com/users/machisuji/received_events","type":"User","site_admin":false},"repo":{"id":13411557,"name":"openproject","full_name":"machisuji/openproject","owner":{"login":"machisuji","id":158871,"avatar_url":"https://avatars.githubusercontent.com/u/158871?v=3","gravatar_id":"","url":"https://api.github.com/users/machisuji","html_url":"https://github.com/machisuji","followers_url":"https://api.github.com/users/machisuji/followers","following_url":"https://api.github.com/users/machisuji/following{/other_user}","gists_url":"https://api.github.com/users/machisuji/gists{/gist_id}","starred_url":"https://api.github.com/users/machisuji/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/machisuji/subscriptions","organizations_url":"https://api.github.com/users/machisuji/orgs","repos_url":"https://api.github.com/users/machisuji/repos","events_url":"https://api.github.com/users/machisuji/events{/privacy}","received_events_url":"https://api.github.com/users/machisuji/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/machisuji/openproject","description":"OpenProject is a web based project management system built on Ruby on Rails","fork":true,"url":"https://api.github.com/repos/machisuji/openproject","forks_url":"https://api.github.com/repos/machisuji/openproject/forks","keys_url":"https://api.github.com/repos/machisuji/openproject/keys{/key_id}","collaborators_url":"https://api.github.com/repos/machisuji/openproject/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/machisuji/openproject/teams","hooks_url":"https://api.github.com/repos/machisuji/openproject/hooks","issue_events_url":"https://api.github.com/repos/machisuji/openproject/issues/events{/number}","events_url":"https://api.github.com/repos/machisuji/openproject/events","assignees_url":"https://api.github.com/repos/machisuji/openproject/assignees{/user}","branches_url":"https://api.github.com/repos/machisuji/openproject/branches{/branch}","tags_url":"https://api.github.com/repos/machisuji/openproject/tags","blobs_url":"https://api.github.com/repos/machisuji/openproject/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/machisuji/openproject/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/machisuji/openproject/git/refs{/sha}","trees_url":"https://api.github.com/repos/machisuji/openproject/git/trees{/sha}","statuses_url":"https://api.github.com/repos/machisuji/openproject/statuses/{sha}","languages_url":"https://api.github.com/repos/machisuji/openproject/languages","stargazers_url":"https://api.github.com/repos/machisuji/openproject/stargazers","contributors_url":"https://api.github.com/repos/machisuji/openproject/contributors","subscribers_url":"https://api.github.com/repos/machisuji/openproject/subscribers","subscription_url":"https://api.github.com/repos/machisuji/openproject/subscription","commits_url":"https://api.github.com/repos/machisuji/openproject/commits{/sha}","git_commits_url":"https://api.github.com/repos/machisuji/openproject/git/commits{/sha}","comments_url":"https://api.github.com/repos/machisuji/openproject/comments{/number}","issue_comment_url":"https://api.github.com/repos/machisuji/openproject/issues/comments{/number}","contents_url":"https://api.github.com/repos/machisuji/openproject/contents/{+path}","compare_url":"https://api.github.com/repos/machisuji/openproject/compare/{base}...{head}","merges_url":"https://api.github.com/repos/machisuji/openproject/merges","archive_url":"https://api.github.com/repos/machisuji/openproject/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/machisuji/openproject/downloads","issues_url":"https://api.github.com/repos/machisuji/openproject/issues{/number}","pulls_url":"https://api.github.com/repos/machisuji/openproject/pulls{/number}","milestones_url":"https://api.github.com/repos/machisuji/openproject/milestones{/number}","notifications_url":"https://api.github.com/repos/machisuji/openproject/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/machisuji/openproject/labels{/name}","releases_url":"https://api.github.com/repos/machisuji/openproject/releases{/id}","created_at":"2013-10-08T11:29:35Z","updated_at":"2014-03-21T14:03:32Z","pushed_at":"2015-04-10T07:31:54Z","git_url":"git://github.com/machisuji/openproject.git","ssh_url":"git@github.com:machisuji/openproject.git","clone_url":"https://github.com/machisuji/openproject.git","svn_url":"https://github.com/machisuji/openproject","homepage":"https://openproject.org","size":62218,"stargazers_count":0,"watchers_count":0,"language":"Ruby","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"feature/rails3"}},"base":{"label":"opf:dev","ref":"dev","sha":"1137eb2c5707b45b8e935f0595f79bb2a952f4c2","user":{"login":"opf","id":1756674,"avatar_url":"https://avatars.githubusercontent.com/u/1756674?v=3","gravatar_id":"","url":"https://api.github.com/users/opf","html_url":"https://github.com/opf","followers_url":"https://api.github.com/users/opf/followers","following_url":"https://api.github.com/users/opf/following{/other_user}","gists_url":"https://api.github.com/users/opf/gists{/gist_id}","starred_url":"https://api.github.com/users/opf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opf/subscriptions","organizations_url":"https://api.github.com/users/opf/orgs","repos_url":"https://api.github.com/users/opf/repos","events_url":"https://api.github.com/users/opf/events{/privacy}","received_events_url":"https://api.github.com/users/opf/received_events","type":"Organization","site_admin":false},"repo":{"id":6899875,"name":"openproject","full_name":"opf/openproject","owner":{"login":"opf","id":1756674,"avatar_url":"https://avatars.githubusercontent.com/u/1756674?v=3","gravatar_id":"","url":"https://api.github.com/users/opf","html_url":"https://github.com/opf","followers_url":"https://api.github.com/users/opf/followers","following_url":"https://api.github.com/users/opf/following{/other_user}","gists_url":"https://api.github.com/users/opf/gists{/gist_id}","starred_url":"https://api.github.com/users/opf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opf/subscriptions","organizations_url":"https://api.github.com/users/opf/orgs","repos_url":"https://api.github.com/users/opf/repos","events_url":"https://api.github.com/users/opf/events{/privacy}","received_events_url":"https://api.github.com/users/opf/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/opf/openproject","description":"OpenProject is a web-based project management system built on Ruby on Rails","fork":false,"url":"https://api.github.com/repos/opf/openproject","forks_url":"https://api.github.com/repos/opf/openproject/forks","keys_url":"https://api.github.com/repos/opf/openproject/keys{/key_id}","collaborators_url":"https://api.github.com/repos/opf/openproject/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/opf/openproject/teams","hooks_url":"https://api.github.com/repos/opf/openproject/hooks","issue_events_url":"https://api.github.com/repos/opf/openproject/issues/events{/number}","events_url":"https://api.github.com/repos/opf/openproject/events","assignees_url":"https://api.github.com/repos/opf/openproject/assignees{/user}","branches_url":"https://api.github.com/repos/opf/openproject/branches{/branch}","tags_url":"https://api.github.com/repos/opf/openproject/tags","blobs_url":"https://api.github.com/repos/opf/openproject/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/opf/openproject/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/opf/openproject/git/refs{/sha}","trees_url":"https://api.github.com/repos/opf/openproject/git/trees{/sha}","statuses_url":"https://api.github.com/repos/opf/openproject/statuses/{sha}","languages_url":"https://api.github.com/repos/opf/openproject/languages","stargazers_url":"https://api.github.com/repos/opf/openproject/stargazers","contributors_url":"https://api.github.com/repos/opf/openproject/contributors","subscribers_url":"https://api.github.com/repos/opf/openproject/subscribers","subscription_url":"https://api.github.com/repos/opf/openproject/subscription","commits_url":"https://api.github.com/repos/opf/openproject/commits{/sha}","git_commits_url":"https://api.github.com/repos/opf/openproject/git/commits{/sha}","comments_url":"https://api.github.com/repos/opf/openproject/comments{/number}","issue_comment_url":"https://api.github.com/repos/opf/openproject/issues/comments{/number}","contents_url":"https://api.github.com/repos/opf/openproject/contents/{+path}","compare_url":"https://api.github.com/repos/opf/openproject/compare/{base}...{head}","merges_url":"https://api.github.com/repos/opf/openproject/merges","archive_url":"https://api.github.com/repos/opf/openproject/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/opf/openproject/downloads","issues_url":"https://api.github.com/repos/opf/openproject/issues{/number}","pulls_url":"https://api.github.com/repos/opf/openproject/pulls{/number}","milestones_url":"https://api.github.com/repos/opf/openproject/milestones{/number}","notifications_url":"https://api.github.com/repos/opf/openproject/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/opf/openproject/labels{/name}","releases_url":"https://api.github.com/repos/opf/openproject/releases{/id}","created_at":"2012-11-28T09:59:11Z","updated_at":"2015-04-09T14:56:46Z","pushed_at":"2015-04-10T07:49:20Z","git_url":"git://github.com/opf/openproject.git","ssh_url":"git@github.com:opf/openproject.git","clone_url":"https://github.com/opf/openproject.git","svn_url":"https://github.com/opf/openproject","homepage":"https://www.openproject.org","size":190548,"stargazers_count":575,"watchers_count":575,"language":"Ruby","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":255,"mirror_url":null,"open_issues_count":58,"forks":255,"open_issues":58,"watchers":575,"default_branch":"dev"}},"_links":{"self":{"href":"https://api.github.com/repos/opf/openproject/pulls/2807"},"html":{"href":"https://github.com/opf/openproject/pull/2807"},"issue":{"href":"https://api.github.com/repos/opf/openproject/issues/2807"},"comments":{"href":"https://api.github.com/repos/opf/openproject/issues/2807/comments"},"review_comments":{"href":"https://api.github.com/repos/opf/openproject/pulls/2807/comments"},"review_comment":{"href":"https://api.github.com/repos/opf/openproject/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/opf/openproject/pulls/2807/commits"},"statuses":{"href":"https://api.github.com/repos/opf/openproject/statuses/23eeb171f777b0bb8b774043cdbd687a58362a86"}}}}