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-21 23:30] – [How to authenticate] dru
Line 1: Line 1:
 ====== JSON API Authentication ====== ====== JSON API Authentication ======
  
-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.+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: 
 +  * [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP Basic authentication (BA)]]. 
 +  * Header Authentication using the HTTP headers 'username' and 'password'. 
 +  * Cookie Authentication using the session cookie returned after a successfull authentication with one of the upper two variants.
  
-==== How to authenticate ====+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". 
 +==== /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. 
-HTTP header fields: 
-| <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 === === Examples ===
-== Request HTTP == + 
-Example request: +== HTTP ==
 <code> <code>
-https://example.protogrid.com/api/v2/authenticate+POST /api/v2/authenticate 
 +Host: example.protogrid.com 
 +username: example_user 
 +password: test_password
 </code> </code>
-Request header:  
-<code json> 
-{ 
-  POST /api/v2/authenticate 
-  Host: your_environment.protogrid.com 
-  user_id: example_user 
-  user_secret: example_secret 
-} 
-</code> 
-== Request jQuery == 
-Example in jQuery: 
  
-<code jquery>+== jQuery == 
 +<code javascript>
 $.ajax({ $.ajax({
   type:'POST',   type:'POST',
Line 37: Line 29:
   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", user_secret="test_password")
 req = requests.post(url, headers=headers) req = requests.post(url, headers=headers)
 response = req.text response = req.text
Line 55: Line 47:
  
 == Request Axios == == Request Axios ==
-Example with Axios 
 <code javascript> <code javascript>
 const axios = require('axios'); const axios = require('axios');
Line 61: Line 52:
   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 64:
 }) })
 .catch((error) => { .catch((error) => {
-  console.error('Outer Error: ' + error);+  console.error('Authentication Error: ' + error);
 }); });
 </code> </code>
Line 82: Line 73:
 { {
   "errors": [],   "errors": [],
-  "protogrid_environment_version": "1.3.9",+  "protogrid_environment_version": "2.3.0",
   "result": "Login successful!"   "result": "Login successful!"
 } }
Line 89: Line 80:
 == Unsuccessful Response == == Unsuccessful Response ==
 Example response of unsuccessful authentication: Example response of unsuccessful authentication:
-<code javascript>+<code json>
 { {
   “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”: {}
 } }

Trace:

Print/export