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
Last revisionBoth sides next revision
protogrid:json_api_authentication [2022-02-21 23:30] – [How to authenticate] druprotogrid:json_api_authentication [2024-04-20 19:24] – 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: 
-  * [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP Basic authentication (BA)]]. +  * 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)]] 
-  * 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. "user@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 ====+
  
 +===== Cross-Origin Resource Sharing (CORS) =====
 +If you want to call the JSON API from the web client of another application or website, i.e. from a domain other than the Protogrid environment, a CORS configuration must first be set up for this. If this has not been done yet, please contact [[protogrid-customer-support@ategra.ch|Protogrid Support]].
 +
 +Please note that for security reasons, authentication using cookies is not possible in this context, i.e. each individual request must be called with either basic or header authentication.
 +
 +===== /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 49:
 </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 60:
 </code> </code>
  
-== Request Axios ==+==== Axios ====
 <code javascript> <code javascript>
 const axios = require('axios'); const axios = require('axios');
Line 68: Line 82:
 </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 92:
 </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 124:
   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 143:
 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 154:
 }) })
 .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