====== 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 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).

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".

===== Cross-Origin Resource Sharing (CORS) =====
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]].

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.

===== /api/v2/authenticate =====
[POST] In order to obtain a session cookie you can use the authentication endpoint.

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>
{
  "username": "testuser@example.com",
  "password": "test_password"
}
</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({
  type:'POST',
  url: 'https://example.protogrid.com/api/v2/authenticate',
  contentType: 'application/json; charset=utf-8',
  dataType: 'json',
  beforeSend: function(xhr){
      xhr.setRequestHeader('username','testuser@example.com');
      xhr.setRequestHeader('password','test_password');
  }
});
</code>

==== Python ====
<code python>
import requests
url = "https://example.protogrid.com/api/v2/authenticate"
headers = dict(username="testuser@example.com", password="test_password")
req = requests.post(url, headers=headers)
response = req.text
response = json.loads(response)
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:
<code javascript>
{
  "errors": [],
  "protogrid_environment_version": "2.3.0",
  "result": "Login successful!"
}
</code>

==== Error Response ====
Example response of unsuccessful authentication:
<code javascript>
{
  "errors": [
    {
      "code": 403,
      "message": "Your login wasn’t recognized."
    }
  ], 
  "protogrid_environment_version": "2.3.0",
  "result": {}
}
</code>

===== Examples using a previously obtained session cookie =====

==== HTTP ====
<code>
GET /api/v2/apps
Host: example.protogrid.com
Cookie: session=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo
</code>

==== jQuery ====
<code javascript>
$.ajax({
  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);
  }
});
</code>
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]].

==== Python ====
<code python>
# The cookie variable was set above in the authentication example.
url = "https://example.protogrid.com/api/v2/apps"
req = requests.get(url, cookies=cookie)
response = req.text
response = json.loads(response)
</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>