Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
protogrid:json_api_authentication [2022-02-21 23:31] – [JSON API Authentication] druprotogrid:json_api_authentication [2022-02-22 23:09] (current) – [/api/v2/authenticate] dru
Line 1: Line 1:
 ====== JSON API Authentication ====== ====== JSON API Authentication ======
 +All HTTP requests to the Protogrid JSON API require a valid authentication. If the authentication fails an HTTP error 403 will be returned.
  
-All HTTP requests to the Protogrid JSON API require a valid authentication. If the authentication fails, an HTTP error 403 will be returned. Currently, the following variants are available for authentication: +The following variants are available for authentication in all JSON API endpoints: 
-  * Header Authentication using the HTTP headers 'username' and 'password'. +  * Header authentication using the HTTP headers 'username' and 'password'. 
-  * [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP Basic authentication (BA)]] +  * [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP basic authentication (BA)]] 
-  * Cookie Authentication using the session cookie returned after a successfull authentication with one of the upper two variants.+  * Cookie authentication (a valid session cookie is part of the response of each successful authenticated JSON API request).
  
-Note: Both the email address (e.g. "testuser@example.com") and the user ID (e.g. "1957f847-f298-4f14-a031-7ffbe31aeb47") can be used for " username". +Note: Both the email address (e.g. "testuser@example.com") and the user ID (e.g. "1957f847-f298-4f14-a031-7ffbe31aeb47") can be used for "username".
-==== /api/v2/authenticate ====+
  
 +===== /api/v2/authenticate =====
 [POST] In order to obtain a session cookie you can use the authentication endpoint. [POST] In order to obtain a session cookie you can use the authentication endpoint.
  
-=== Examples ===+Note: For this endpoint, in addition to the three variants above, the credentials can also be passed as "application/json" in the request body: 
 +<code javascript> 
 +{ 
 +  "username": "testuser@example.com", 
 +  "password": "test_password" 
 +} 
 +</code> 
 + 
 +===== Examples obtaining a session cookie using the authentication endpoint with header authentication =====
  
-== HTTP ==+==== HTTP ====
 <code> <code>
 POST /api/v2/authenticate POST /api/v2/authenticate
 Host: example.protogrid.com Host: example.protogrid.com
-username: example_user+username: testuser@example.com
 password: test_password password: test_password
 </code> </code>
  
-== jQuery ==+==== jQuery ====
 <code javascript> <code javascript>
 $.ajax({ $.ajax({
Line 35: Line 44:
 </code> </code>
  
-== Python ==+==== Python ====
 <code python> <code python>
 import requests import requests
 url = "https://example.protogrid.com/api/v2/authenticate" url = "https://example.protogrid.com/api/v2/authenticate"
-headers = dict(username="testuser@example.com", user_secret="test_password")+headers = dict(username="testuser@example.com", password="test_password")
 req = requests.post(url, headers=headers) req = requests.post(url, headers=headers)
 response = req.text response = req.text
Line 46: Line 55:
 </code> </code>
  
-== Request Axios ==+==== Axios ====
 <code javascript> <code javascript>
 const axios = require('axios'); const axios = require('axios');
Line 68: Line 77:
 </code> </code>
  
-== Success Response ==+==== Success Response ====
 Example response of successful authentication: Example response of successful authentication:
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
Line 78: Line 87:
 </code> </code>
  
-== Unsuccessful Response ==+==== Error Response ====
 Example response of unsuccessful authentication: Example response of unsuccessful authentication:
-<code json>+<code javascript>
 { {
-  “errors”: [+  "errors": [
     {     {
-      “code”: 403, +      "code": 403, 
-      “message”: “Your login wasn’t recognized.”+      "message": "Your login wasn’t recognized."
     }     }
   ],    ], 
   "protogrid_environment_version": "2.3.0",   "protogrid_environment_version": "2.3.0",
-  “result”: {}+  "result": {}
 } }
 </code> </code>
  
-==== How to send authenticated http requests ==== +===== Examples using a previously obtained session cookie =====
-Each request to any API endpoint has to be authenticated using the cookie returned by the /api/v2/authenticate API endpoint. +
  
-=== Examples === +==== HTTP ==== 
-== ajax == +<code> 
-Example ajax request: +GET /api/v2/apps 
-Note that when jQuery runs in a browser, that the cookie is passed automatically with the request. +Host: example.protogrid.com 
-<code jquery> +Cookie: session=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo 
-$jq.ajax({+</code> 
 + 
 +==== jQuery ==== 
 +<code javascript> 
 +$.ajax({
   type: 'GET',   type: 'GET',
   url: 'https://example.protogrid.com/api/v2/apps',   url: 'https://example.protogrid.com/api/v2/apps',
Line 107: Line 119:
   dataType: 'json',   dataType: 'json',
   success: function(data) {   success: function(data) {
-          console.log(data);+    console.log(data);
   },   },
-  error: function(data) { console.log(data); }+  error: function(data) { 
 +    console.log(data); 
 +  }
 }); });
 </code> </code>
-Note: Some browsers handle cookies differently. For more information, see the browser specific documentation.+Most browsers automatically save received cookies and then automatically attach them to subsequent requests. 
 + 
 +In particular, this means that you usually don't need to worry about authentication if you use JSON API requests in [[protogrid:script_library|Client Script Libraries]].
  
-== Example Python == +==== Python ====
-Example Python request:+
 <code python> <code python>
-# The cookie variable was set above in the authenticate example.+# The cookie variable was set above in the authentication example.
 url = "https://example.protogrid.com/api/v2/apps" url = "https://example.protogrid.com/api/v2/apps"
 req = requests.get(url, cookies=cookie) req = requests.get(url, cookies=cookie)
Line 123: Line 138:
 response = json.loads(response) response = json.loads(response)
 </code> </code>
-Note: For more information about the requests, please refer to http://docs.python-requests.org/en/master/+For more information about the requests library, please refer to [[http://docs.python-requests.org/en/master/|the official documentation]].
  
-== Example Axios == +==== Axios ====
-Example request with Axios:+
 <code javascript> <code javascript>
 axios.get('https://example.protogrid.com/api/v2/apps', { axios.get('https://example.protogrid.com/api/v2/apps', {
Line 135: Line 149:
 }) })
 .then((result) => { .then((result) => {
-  console.log('Inner Success.');+  console.log('Success');
   console.log(result.data);   console.log(result.data);
 }) })
 .catch((error) => { .catch((error) => {
-  console.log('Inner Error: ' + error);+  console.log('Error'); 
 +  console.log(error);
 }); });
 </code> </code>
  

Trace:

Print/export