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 11:37] 46.140.51.3protogrid: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.
  
-At the moment only Basic Authentication is supportedIf 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 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 (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. +===== /api/v2/authenticate ===== 
-HTTP Header fields: +[POSTIn order to obtain a session cookie you can use the authentication endpoint
-| <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.| +NoteFor this endpoint, in addition to the three variants above, the credentials can also be passed as "application/json" in the request body
-| <user_email> [required]|The user_email corresponds to the e-mail address of the user. | +<code javascript>
-| ::: |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", 
- Hostyour_environment.protogrid.com +  "password""test_password"
- user_id: example_user +
- user_secretexample_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', 
-    url: 'https://example.protogrid.com/api/v2/authenticate', +  url: 'https://example.protogrid.com/api/v2/authenticate', 
-    contentType: 'application/json; charset=utf-8', +  contentType: 'application/json; charset=utf-8', 
-    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 55:
 </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 json>+<code javascript>
 { {
-errors: [ +  "errors": [ 
- +    
- code401+      "code"403
- messageYour login wasn’t recognized. Please check your e-mail +      "message""Your login wasn’t recognized." 
- address and password.” +    
- +  ],  
- ],  +  "protogrid_environment_version": "2.3.0", 
- "protogrid_environment_version": "1.3.9", +  "result": {}
- result: {}+
 } }
 </code> </code>
  
-How to send authenticated http requests +===== Examples using a previously obtained session cookie ===== 
-Each request to the API must be authenticated using the cookie the /api/v2/authenticate API endpoint returns.  + 
-Example ajax request+==== HTTP ==== 
-Note that when jQuery runs in a browser, that the cookie is passed automatically with the request. +<code> 
-<code jquery+GET /api/v2/apps 
-$jq.ajax({ +Host: example.protogrid.com 
-        type: 'GET', +Cookiesession=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo 
-        url: 'https://example.protogrid.com/api/v2/apps', +</code> 
-        contentType: 'application/json; charset=utf-8', + 
-        dataType: 'json', +==== jQuery ==== 
-        success: function(data) { +<code javascript
-                console.log(data); +$.ajax({ 
-        }, +  type: 'GET', 
-        error: function(data) { console.log(data); }+  url: 'https://example.protogrid.com/api/v2/apps', 
 +  contentType: 'application/json; charset=utf-8', 
 +  dataType: 'json', 
 +  success: function(data) { 
 +    console.log(data); 
 +  }, 
 +  error: function(data) { 
 +    console.log(data); 
 +  }
 }); });
 </code> </code>
-Note: Some browsers handle cookies differentlyFor more informationsee the browser specific documentation+Most browsers automatically save received cookies and then automatically attach them to subsequent requests. 
-Example Python request:+ 
 +In particularthis means that you usually don't need to worry about authentication if you use JSON API requests in [[protogrid:script_library|Client Script Libraries]]
 + 
 +==== 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 105: 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]]. 
 + 
 +==== 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>
  
Print/export