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
Next revisionBoth sides next revision
protogrid:json_api_authentication [2019-12-18 15:51] – jusprotogrid:json_api_authentication [2022-02-22 00:12] – 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. The following variants are available for authentication:
 +  * 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.
  
-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.+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".
  
-==== How to authenticate ====+==== /api/v2/authenticate ==== 
 +[POST] In order to obtain a session cookie you can use the authentication endpoint.
  
-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. +For this endpoint, in addition to the three variants above, the credentials can also be passed as JSON in the request body: 
-HTTP header fields: +<code javascript>
-| <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.| +
-| <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.| +
-|<user_secret> [required]: |The user_secret corresponds to the password of the user.| +
-=== Examples === +
-== Request HTTP == +
-Example request:  +
-<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 to obtain 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 36:
   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 53:
 </code> </code>
  
-== Request Axios == +=== Axios ===
-Example with Axios+
 <code javascript> <code javascript>
 const axios = require('axios'); const axios = require('axios');
Line 61: Line 59:
   headers: {   headers: {
     'Content-Type': 'application/json; charset=utf-8',     'Content-Type': 'application/json; charset=utf-8',
-    'user_email': 'test_user@testdomain.com', +    'username': 'testuser@example.com', 
-    'user_secret': 'test_password'+    'password': 'test_password'
   }   }
 }) })
 .then((result) => { .then((result) => {
-  console.log('Outer Success.');+  console.log('Authentication Success.');
   var cookies_from_resp = res.headers['set-cookie'];   var cookies_from_resp = res.headers['set-cookie'];
   var cookie_for_session = cookies_from_resp[0].split(';').[0];   var cookie_for_session = cookies_from_resp[0].split(';').[0];
Line 73: Line 71:
 }) })
 .catch((error) => { .catch((error) => {
-  console.error('Outer Error: ' + error);+  console.error('Authentication Error: ' + error);
 }); });
 </code> </code>
  
-== Success Response ==+=== 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 ==== +==== Example HTTP requests 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 117: Line 117:
   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 133: Line 136:
 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 145: Line 147:
 }) })
 .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