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'.
• HTTP Basic authentication (BA)
• 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”.

[POST] In order to obtain a session cookie you can use the authentication endpoint.

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

$.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.

# 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);
});