This is an old revision of the document!
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:
- Header authentication using the HTTP headers 'username' and 'password'.
- Cookie authentication using the session cookie returned after a successfull authentication with one of the upper two variants.
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.
For this endpoint, in addition to the three variants above, the credentials can also be passed as JSON in the request body:
{ "username": "testuser@example.com", "password": "test_password" }
Examples to obtain 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": {} }
Example HTTP requests 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); });