This is an old revision of the document!


JSON API Authentication

At the moment only Basic Authentication is supported. If you need OAuth2 please contact us at protogrid-support@protogrid.com. All http requests require an authentication. If the authentication fails, an error will be returned. The error describes whether a HTTP Header field is missing or the login data is incorrect.

How to authenticate

A POST http request to the API endpoint “/api/v2/authenticate” does log in the user and the response contains the set-cookie header with the generated cookie. HTTP Header fields:

<user_id> [required]: The user_id corresponds to the username or e-mail address of the user.
Either <user_email> or <user_id> have to be specified.
<user_email> [required]: The user_email corresponds to the e-mail address of the user.
Either <user_email> or <user_id> have to be specified.
<user_secret> [required]: The user_secret corresponds to the password of the user.

Example request:

https://example.protogrid.com/api/v2/authenticate

Request Header:

{
	POST /api/v2/authenticate
	Host: your_environment.protogrid.com
	user_id: example_user
	user_secret: example_secret
}

Example in 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('user_id','tester@test.com');
        xhr.setRequestHeader('user_secret','test_password');
    }
});

Example in Python (with requests):

url = "https://example.protogrid.com/api/v2/authenticate"
headers = dict(user_id="test_user@testdomain.com", user_secret="test_password")
req = requests.post(url, headers=headers)
response = req.text
response = json.loads(response)
cookie = req.cookies['session']

Example response of successful authentication:

{
	"errors": [],
	"protogrid_environment_version": "1.3.9",
	"result": "Login successful!"
}

Example response of unsuccessful authentication:

{
	“errors”: [
		{
			“code”: 401,
			“message”: “Your login wasn’t recognized. Please check your e-mail
			address and password.”
		}
	], 
	"protogrid_environment_version": "1.3.9",
	“result”: {}
}

How to send authenticated http requests Each request to the API must be authenticated using the cookie the /api/v2/authenticate API endpoint returns. Example ajax request: Note that when jQuery runs in a browser, that the cookie is passed automatically with the request. $jq.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); }

}); Note: Some browsers handle cookies differently. For more information, see the browser specific documentation. Example Python request: The cookie variable was set above in the authenticate example. url = “https://example.protogrid.com/api/v2/apps” req = requests.get(url, cookies=cookie) response = req.text response = json.loads(response) Note: For more information about the requests, please refer to http://docs.python-requests.org/en/master/

Print/export