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. “user@example.com”) and the user ID (e.g. “1957f847-f298-4f14-a031-7ffbe31aeb47”) can be used for “ username”.
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. |
Examples
Request HTTP
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 }
Request jQuery
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'); } });
Request Python
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']
Request Axios
Example with Axios
const axios = require('axios'); axios.post('https://example.protogrid.com/api/v2/authenticate', {}, { headers: { 'Content-Type': 'application/json; charset=utf-8', 'user_email': 'test_user@testdomain.com', 'user_secret': 'test_password' } }) .then((result) => { console.log('Outer 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('Outer Error: ' + error); });
Success Response
Example response of successful authentication:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result": "Login successful!" }
Unsuccessful Response
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 any API endpoint has to be authenticated using the cookie returned by the /api/v2/authenticate API endpoint.
Examples
ajax
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
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/
Example Axios
Example request with 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('Inner Success.'); console.log(result.data); }) .catch((error) => { console.log('Inner Error: ' + error); });