Table of Contents
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'.
- 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”.
/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:
{ "username": "testuser@example.com", "password": "test_password" }
Examples obtaining a session cookie using the authentication endpoint with header authentication
HTTP
POST /api/v2/authenticate Host: example.protogrid.com username: testuser@example.com password: test_password
jQuery
$.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'); } });
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']
Axios
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); });
Success Response
Example response of successful authentication:
{ "errors": [], "protogrid_environment_version": "2.3.0", "result": "Login successful!" }
Error Response
Example response of unsuccessful authentication:
{ "errors": [ { "code": 403, "message": "Your login wasn’t recognized." } ], "protogrid_environment_version": "2.3.0", "result": {} }
Examples using a previously obtained session cookie
HTTP
GET /api/v2/apps Host: example.protogrid.com Cookie: session=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo
jQuery
$.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.
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)
For more information about the requests library, please refer to the official documentation.
Axios
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); });