This article describes the OAuth process, which allows users to request an API key from their Quentn system. When your app is built on PHP, we strongly recommend to use our PHP-SDK. Otherwise you have to implement the process manually, as descibed in this document.
Before you can start, you have to register an app at my.quentn.com to get client_id and client_secret. Please contact Quentn support to do so.
Start process
The Oauth process has to be initiated with an HTTP GET request.
Example request:
GET https://my.quentn.com/public/api/v1/oauth?response_type=code&scope=all&client_id=<client_id-of-your-app>&redirect_uri=<redirect_uri>&state=<random_string> HTTP/1.1| Parameter name | Value | Description |
|---|---|---|
| response_type | code | |
| scope | all | Scope of the API key. |
| client_id | <client_id-of-your-app> | You will get the client id when registering your app. |
| redirect_uri | <redirect_uri> | User will be redirected to that URL after this step was completed. The domain must match the domain which was specified on app registration. |
| state | <random_string> | A random string, which will be appended as parameter to the redirect_uri to validate the request. |
The user has to select a Quentn systems to connect with. Then, he will be redirected to the given redirect_uri. The following parameters will be appended:
| Parameter name | Value | Description |
|---|---|---|
| code | <token_for_next_request> | Use this token in the next step when requesting the actual API key. |
| state | <random_string_from_last_step> | Make sure this string matches the given state from the initial request. Otherwise the process should be stopped because it cannot be considered as secure anymore. |
Request API key
Get the API key during HTTP POST request.
Example request:
POST https://my.quentn.com/public/api/v1/oauth/request HTTP/1.1
Content-Type: application/json
{
"grant_type": "authorization_code",
"code": "<token_from_last_request>",
"client_id": "<client_id-of-your-app>",
"client_secret": "<client_secret-of-your-app>",
"redirect_uri": "<redirect_uri>",
"app_context": "<account_id_in_your_system>",
}| Parameter name | Value | Description |
|---|---|---|
| grant_type | authorization_code | |
| code | <token_from_last_request> | This is the token you have got during redirection in the last step. |
| client_id | <client_id-of-your-app> | You will get the client id when registering your app. |
| client_secret | <client_secret-of-your-app> | You will get the client secret when registering your app. |
| redirect_uri | <redirect_uri> | The domain must match the domain which was specified on app registration. |
| app_context | <account_id_in_your_system> | Optional: you can give e. g. the users account ID in your app. This is necessary if your users should be able to connect multiple instances of your app with the same Quentn system. Type must be UTF8 string with up to 64 characters. |
Example response:
In case of fail:
HTTP/1.1 400 Bad request
Content-Type: application/json
{
"error": "true",
"message": "Some error message",
}In case of success:
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": "true",
"api-key": "<your-api-key>",
"base-url": "<base_url_for_api_requests>",
}| Parameter name | Value | Description |
|---|---|---|
| success | true | |
| api-key | <your-api-key> | Use this key to make API requests. |
| base-url | <base_url_for_api_requests> | This is the base URL for API requests. |