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 [2022-02-21 23:48] – [How to send authenticated http requests] druprotogrid:json_api_authentication [2024-04-20 19:24] (current) – [Cross-Origin Resource Sharing (CORS)] 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.
  
-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: +The following variants are available for authentication in all JSON API endpoints: 
-  * Header Authentication using the HTTP headers 'username' and 'password'. +  * Header authentication using the HTTP headers 'username' and 'password'. 
-  * [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP Basic authentication (BA)]] +  * [[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.+  * 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". +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".
-==== /api/v2/authenticate ====+
  
 +===== 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. [POST] In order to obtain a session cookie you can use the authentication endpoint.
  
-=== Examples ===+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 ==+==== HTTP ====
 <code> <code>
 POST /api/v2/authenticate POST /api/v2/authenticate
Line 21: Line 35:
 </code> </code>
  
-== jQuery ==+==== jQuery ====
 <code javascript> <code javascript>
 $.ajax({ $.ajax({
Line 35: Line 49:
 </code> </code>
  
-== Python ==+==== Python ====
 <code python> <code python>
 import requests import requests
Line 46: Line 60:
 </code> </code>
  
-== Axios ==+==== Axios ====
 <code javascript> <code javascript>
 const axios = require('axios'); const axios = require('axios');
Line 68: Line 82:
 </code> </code>
  
-== Success Response ==+==== Success Response ====
 Example response of successful authentication: Example response of successful authentication:
 <code javascript> <code javascript>
Line 78: Line 92:
 </code> </code>
  
-== Error Response ==+==== Error Response ====
 Example response of unsuccessful authentication: Example response of unsuccessful authentication:
 <code javascript> <code javascript>
Line 93: Line 107:
 </code> </code>
  
-=== Example HTTP requests using the previously obtained session cookie ===+===== Examples using a previously obtained session cookie =====
  
-== AJAX ==+==== HTTP ==== 
 +<code> 
 +GET /api/v2/apps 
 +Host: example.protogrid.com 
 +Cookie: session=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo 
 +</code> 
 + 
 +==== jQuery ====
 <code javascript> <code javascript>
 $.ajax({ $.ajax({
Line 112: Line 133:
 Most browsers automatically save received cookies and then automatically attach them to subsequent requests. Most browsers automatically save received cookies and then automatically attach them to subsequent requests.
  
-== Python ==+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> <code python>
 # The cookie variable was set above in the authentication example. # The cookie variable was set above in the authentication example.
Line 122: Line 145:
 For more information about the requests library, please refer to [[http://docs.python-requests.org/en/master/|the official documentation]]. For more information about the requests library, please refer to [[http://docs.python-requests.org/en/master/|the official documentation]].
  
-== Axios ==+==== Axios ====
 <code javascript> <code javascript>
 axios.get('https://example.protogrid.com/api/v2/apps', { axios.get('https://example.protogrid.com/api/v2/apps', {

Trace:

Print/export