Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
protogrid:json_api_authentication [2017-12-08 11:39] – 46.140.51.3 | protogrid:json_api_authentication [2024-04-20 19:24] – dru | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== JSON API Authentication ====== | ====== 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. | ||
- | At the moment only Basic Authentication is supported. If you need OAuth2 please contact us at [[mailto:protogrid-support@protogrid.com|protogrid-support@protogrid.com]]. All http requests require an authentication. If the authentication fails, an error will be returned. The error describes whether | + | The following variants are available for authentication in all JSON API endpoints: |
+ | * Header authentication using the HTTP headers ' | ||
+ | * [[https://en.wikipedia.org/ | ||
+ | * Cookie | ||
- | ==== How to authenticate ==== | + | Note: Both the email address (e.g. " |
- | A POST http request | + | ===== Cross-Origin Resource Sharing (CORS) ===== |
- | HTTP Header fields: | + | If you want to call the JSON API from the web client of another application or website, i.e. from a domain other than the Protogrid environment, |
- | | < | + | |
- | | ::: |Either < | + | Please note that for security reasons, authentication using cookies is not possible in this context, i.e. each individual request must be called with either basic or header authentication. |
- | | < | + | |
- | | ::: |Either < | + | ===== / |
- | |< | + | [POST] In order to obtain a session cookie you can use the authentication endpoint. |
- | === Examples | + | |
- | == Request HTTP == | + | Note: For this endpoint, in addition to the three variants above, the credentials can also be passed as " |
- | Example request: | + | < |
- | < | + | |
- | https:// | + | |
- | </ | + | |
- | Request Header: | + | |
- | < | + | |
{ | { | ||
- | POST / | + | " |
- | Host: your_environment.protogrid.com | + | " |
- | user_id: example_user | + | |
- | user_secret: example_secret | + | |
} | } | ||
</ | </ | ||
- | == Request jQuery == | ||
- | Example in jQuery: | ||
- | < | + | ===== Examples obtaining a session cookie using the authentication endpoint with header authentication ===== |
+ | |||
+ | ==== HTTP ==== | ||
+ | <code> | ||
+ | POST / | ||
+ | Host: example.protogrid.com | ||
+ | username: testuser@example.com | ||
+ | password: test_password | ||
+ | </ | ||
+ | |||
+ | ==== jQuery ==== | ||
+ | <code javascript> | ||
$.ajax({ | $.ajax({ | ||
- | | + | |
- | url: ' | + | url: ' |
- | contentType: | + | contentType: |
- | dataType: ' | + | dataType: ' |
- | beforeSend: function(xhr){ | + | beforeSend: function(xhr){ |
- | xhr.setRequestHeader(' | + | xhr.setRequestHeader(' |
- | xhr.setRequestHeader(' | + | xhr.setRequestHeader(' |
- | } | + | } |
}); | }); | ||
</ | </ | ||
- | == Request Python | + | ==== Python |
- | Example in Python | + | |
<code python> | <code python> | ||
+ | import requests | ||
url = " | url = " | ||
- | headers = dict(user_id="test_user@testdomain.com", | + | headers = dict(username="testuser@example.com", |
req = requests.post(url, | req = requests.post(url, | ||
response = req.text | response = req.text | ||
Line 54: | Line 60: | ||
</ | </ | ||
- | == Success Response == | + | ==== Axios ==== |
+ | <code javascript> | ||
+ | const axios = require(' | ||
+ | axios.post(' | ||
+ | headers: { | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | } | ||
+ | }) | ||
+ | .then((result) => { | ||
+ | console.log(' | ||
+ | var cookies_from_resp = res.headers[' | ||
+ | var cookie_for_session = cookies_from_resp[0].split(';' | ||
+ | |||
+ | // send authenticated http request here (see documentation below) | ||
+ | }) | ||
+ | .catch((error) => { | ||
+ | console.error(' | ||
+ | }); | ||
+ | </ | ||
+ | |||
+ | ==== Success Response | ||
Example response of successful authentication: | Example response of successful authentication: | ||
- | < | + | < |
{ | { | ||
- | " | + | |
- | " | + | " |
- | " | + | " |
} | } | ||
</ | </ | ||
- | == Unsuccessful | + | ==== Error Response |
Example response of unsuccessful authentication: | Example response of unsuccessful authentication: | ||
- | < | + | < |
{ | { | ||
- | “errors”: [ | + | "errors": [ |
- | { | + | { |
- | “code”: 401, | + | " |
- | “message”: “Your login wasn’t recognized. | + | " |
- | address and password.” | + | } |
- | } | + | ], |
- | ], | + | " |
- | " | + | " |
- | “result”: {} | + | |
} | } | ||
</ | </ | ||
- | ==== How to send authenticated http requests | + | ===== Examples using a previously obtained session cookie ===== |
- | Each request to the API must be authenticated using the cookie the / | + | |
- | === Examples | + | ==== HTTP ==== |
- | == ajax == | + | < |
- | Example ajax request: | + | GET / |
- | Note that when jQuery runs in a browser, that the cookie is passed automatically with the request. | + | Host: example.protogrid.com |
- | < | + | Cookie: session=.eJyNsjcfzO7DzDBQxq3cxhPBl1JzwkL4AnjUOkhrJWjN0bOGXd9dpeWmO-337efwDyf4bLA.YhNvyQ.PZSBKOhy94xZ8yLq-e0HwIqo |
- | $jq.ajax({ | + | </ |
- | type: ' | + | |
- | url: ' | + | ==== jQuery ==== |
- | contentType: | + | < |
- | dataType: ' | + | $.ajax({ |
- | success: function(data) { | + | type: ' |
- | console.log(data); | + | url: ' |
- | }, | + | contentType: |
- | error: function(data) { console.log(data); | + | dataType: ' |
+ | success: function(data) { | ||
+ | console.log(data); | ||
+ | }, | ||
+ | error: function(data) { | ||
+ | | ||
+ | | ||
}); | }); | ||
</ | </ | ||
- | Note: Some browsers | + | Most browsers |
+ | |||
+ | In particular, this means that you usually don't need to worry about authentication if you use JSON API requests in [[protogrid: | ||
- | == Example Python | + | ==== Python |
- | Example | + | |
<code python> | <code python> | ||
- | The cookie variable was set above in the authenticate | + | # The cookie variable was set above in the authentication |
url = " | url = " | ||
req = requests.get(url, | req = requests.get(url, | ||
Line 110: | Line 143: | ||
response = json.loads(response) | response = json.loads(response) | ||
</ | </ | ||
- | Note: For more information about the requests, please refer to http:// | + | For more information about the requests |
+ | |||
+ | ==== Axios ==== | ||
+ | <code javascript> | ||
+ | axios.get(' | ||
+ | headers: { | ||
+ | ' | ||
+ | ' | ||
+ | } | ||
+ | }) | ||
+ | .then((result) => { | ||
+ | console.log(' | ||
+ | console.log(result.data); | ||
+ | }) | ||
+ | .catch((error) => { | ||
+ | console.log(' | ||
+ | console.log(error); | ||
+ | }); | ||
+ | </ | ||