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. Currently, 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.
Examples
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 the previously obtained session cookie
AJAX
$.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.
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); });