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 [2017-12-08 09:54] – 46.140.51.3protogrid: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.
  
-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 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]]. 
-| <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. 
-Example request: https://example.protogrid.com/api/v2/authenticate + 
-Request Header: +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>
 { {
- POST /api/v2/authenticate +  "username": "testuser@example.com", 
- Host: your_environment.protogrid.com +  "password": "test_password"
- user_id: example_user +
- user_secret: example_secret+
 } }
-Example in jQuery:+</code> 
 + 
 +===== 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'); 
-    }+  }
 }); });
-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
 response = json.loads(response) response = json.loads(response)
 cookie = req.cookies['session'] cookie = req.cookies['session']
 +</code>
  
 +==== 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 javascript>
 { {
- "errors": [], +  "errors": [], 
- "protogrid_environment_version": "1.3.9", +  "protogrid_environment_version": "2.3.0", 
- "result": "Login successful!"+  "result": "Login successful!"
 } }
 +</code>
 +
 +==== Error Response ====
 Example response of unsuccessful authentication: Example response of unsuccessful authentication:
 +<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": "2.3.0", 
- "protogrid_environment_version": "1.3.9", +  "result": {}
- “result”: {}+
 } }
 +</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> 
-$jq.ajax({ +GET /api/v2/apps 
-        type: 'GET', +Host: example.protogrid.com 
-        url: 'https://example.protogrid.com/api/v2/apps', +Cookie: session=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo 
-        contentType: 'application/json; charset=utf-8', +</code> 
-        dataType: 'json', + 
-        success: function(data) { +==== jQuery ==== 
-                console.log(data); +<code javascript> 
-        }, +$.ajax({ 
-        error: function(data) { console.log(data); }+  type: 'GET', 
 +  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); 
 +  }
 }); });
-Note: Some browsers handle cookies differently. For more information, see the browser specific documentation. +</code> 
-Example Python request: +Most browsers automatically save received cookies and then automatically attach them to subsequent requests. 
-The cookie variable was set above in the authenticate example.+ 
 +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]]. 
 + 
 +==== Python ==== 
 +<code python> 
 +# 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)
 response = req.text response = req.text
 response = json.loads(response) response = json.loads(response)
-Note: For more information about the requests, please refer to http://docs.python-requests.org/en/master/+</code> 
 +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