This is an old revision of the document!


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"
}

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": {}
}

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);
});
Print/export