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 [2017-12-08 17:37] – pgrid_wiki_adminprotogrid:json_api_authentication [2024-04-20 19:24] (current) – [Cross-Origin Resource Sharing (CORS)] 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.
  
-At the moment only Basic Authentication is supported. If you need OAuth2 please contact us at [[mailto:protogrid-support@protogrid.com|protogrid-support@protogrid.com]]. All http requests require an authentication. If the authentication fails, an error will be returned. The error describes whether a HTTP Header field is missing or the login data is incorrect.+The following variants are available for authentication in all JSON API endpoints: 
 +  * Header authentication using the HTTP headers 'username' and 'password'. 
 +  * [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP basic authentication (BA)]] 
 +  * Cookie authentication (a valid session cookie is part of the response of each successful authenticated JSON API request).
  
-==== How to authenticate ====+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".
  
-A POST http request to the API endpoint “/api/v2/authenticate” does log in the user and the response contains the set-cookie header with the generated cookie. +===== Cross-Origin Resource Sharing (CORS) ===== 
-HTTP header fields: +If you want to call the JSON API out of 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]]. 
-| <user_id> [required]: | The user_id corresponds to the username or e-mail address of the user. | + 
-| ::: |Either <user_email> or <user_id> have to be specified.| +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. 
-| <user_email> [required]: |The user_email corresponds to the e-mail address of the user. | + 
-| ::: |Either <user_email> or <user_id> have to be specified.| +===== /api/v2/authenticate ===== 
-|<user_secret> [required]: |The user_secret corresponds to the password of the user.| +[POST] In order to obtain a session cookie you can use the authentication endpoint. 
-=== Examples === + 
-== Request HTTP == +Note: For this endpoint, in addition to the three variants above, the credentials can also be passed as "application/json" in the request body: 
-Example request:  +<code javascript>
-<code> +
-https://example.protogrid.com/api/v2/authenticate +
-</code> +
-Request header:  +
-<code json>+
 { {
-  POST /api/v2/authenticate +  "username": "testuser@example.com", 
-  Host: your_environment.protogrid.com +  "password": "test_password"
-  user_id: example_user +
-  user_secret: example_secret+
 } }
 </code> </code>
-== Request jQuery == 
-Example in jQuery: 
  
-<code jquery>+===== Examples obtaining a session cookie using the authentication endpoint with header authentication ===== 
 + 
 +==== HTTP ==== 
 +<code> 
 +POST /api/v2/authenticate 
 +Host: example.protogrid.com 
 +username: testuser@example.com 
 +password: test_password 
 +</code> 
 + 
 +==== jQuery ==== 
 +<code javascript>
 $.ajax({ $.ajax({
   type:'POST',   type:'POST',
Line 37: Line 43:
   dataType: 'json',   dataType: 'json',
   beforeSend: function(xhr){   beforeSend: function(xhr){
-      xhr.setRequestHeader('user_id','tester@test.com'); +      xhr.setRequestHeader('username','testuser@example.com'); 
-      xhr.setRequestHeader('user_secret','test_password');+      xhr.setRequestHeader('password','test_password');
   }   }
 }); });
 </code> </code>
  
-== Request Python == +==== Python ====
-Example in Python (with requests):+
 <code python> <code python>
 +import requests
 url = "https://example.protogrid.com/api/v2/authenticate" url = "https://example.protogrid.com/api/v2/authenticate"
-headers = dict(user_id="test_user@testdomain.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 54: Line 60:
 </code> </code>
  
-== Success Response ==+==== Axios ==== 
 +<code javascript> 
 +const axios = require('axios'); 
 +axios.post('https://example.protogrid.com/api/v2/authenticate', {}, { 
 +  headers: { 
 +    'Content-Type': 'application/json; charset=utf-8', 
 +    'username': 'testuser@example.com', 
 +    'password': 'test_password' 
 +  } 
 +}) 
 +.then((result) => { 
 +  console.log('Authentication Success.'); 
 +  var cookies_from_resp = res.headers['set-cookie']; 
 +  var cookie_for_session = cookies_from_resp[0].split(';').[0]; 
 +   
 +  // send authenticated http request here (see documentation below) 
 +}) 
 +.catch((error) => { 
 +  console.error('Authentication Error: ' + error); 
 +}); 
 +</code> 
 + 
 +==== Success Response ====
 Example response of successful authentication: Example response of successful authentication:
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
-  "protogrid_environment_version": "1.3.9",+  "protogrid_environment_version": "2.3.0",
   "result": "Login successful!"   "result": "Login successful!"
 } }
 </code> </code>
  
-== Unsuccessful Response ==+==== Error Response ====
 Example response of unsuccessful authentication: Example response of unsuccessful authentication:
 <code javascript> <code javascript>
 { {
-  “errors”: [+  "errors": [
     {     {
-      “code”: 401, +      "code": 403, 
-      “message”: “Your login wasn’t recognized. Please check your e-mail +      "message": "Your login wasn’t recognized."
-      address and password.”+
     }     }
   ],    ], 
-  "protogrid_environment_version": "1.3.9", +  "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 94: 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.
  
-== Example Python == +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 request:+ 
 +==== Python ====
 <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 110: 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]]. 
 + 
 +==== Axios ==== 
 +<code javascript> 
 +axios.get('https://example.protogrid.com/api/v2/apps', { 
 +  headers: { 
 +    'Content-Type': 'application/json; charset=utf-8', 
 +    'Cookie': cookie_for_session // The cookie_for_session variable was set above in the authenticate example. 
 +  } 
 +}) 
 +.then((result) => { 
 +  console.log('Success'); 
 +  console.log(result.data); 
 +}) 
 +.catch((error) => { 
 +  console.log('Error'); 
 +  console.log(error); 
 +}); 
 +</code>
  

Trace:

Print/export