This is an old revision of the document!
Table of Contents
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]: |
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/