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:
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”.
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 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.
[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:
{ "username": "testuser@example.com", "password": "test_password" }
POST /api/v2/authenticate Host: example.protogrid.com username: testuser@example.com password: test_password
$.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'); } });
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']
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); });
Example response of successful authentication:
{ "errors": [], "protogrid_environment_version": "2.3.0", "result": "Login successful!" }
Example response of unsuccessful authentication:
{ "errors": [ { "code": 403, "message": "Your login wasn’t recognized." } ], "protogrid_environment_version": "2.3.0", "result": {} }
GET /api/v2/apps Host: example.protogrid.com Cookie: session=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo
$.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); } });
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 Client Script Libraries.
# 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)
For more information about the requests library, please refer to the official documentation.
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); });