OAuth Authentication implementation, HTTP Response Status Codes and Examples
OAuth Authentication
Lemonway uses the OAuth 2.0 protocol and framework to secure access to our REST API resources. Our authentication service strictly adheres to the IETF framework and standards set out in RFC 6749, Section 4.4.2 - Access Token Request.
For more details, see OAuth 2.0 (External Website)
Disclaimer
Lemonway does not supervise or manage external website content. We provide links to these sites to assist you with technical details beyond the scope of this subject. Unless specified, Lemonway has no control over the material on these external sites.
Note
The steps outlined in this topic apply to both the sandbox and the prod version of the REST API webservices.
Lemonway implements a two-step procedure that grants you secure access to our REST API webservice resources.
-
Generate a basic authentication API key using the Lemonway Dashboard. This step is required to establish Client Authentication with our Authorization Server.
-
Use the basic authentication API Key to request an Access Token of Bearer Type from the Authorization Server. This enables you to securely use Lemonway’s REST API resources.
Important
The basic authentication API key can only be generated using the Lemonway Dashboard. To access the Lemonway Dashboard, use the sign-in credentials emailed to you by the Lemonway onboarding team.
If you do not have access to this application, please contact us at [email protected]
Step 1: Generating a Basic Authentication API Key for Client Authentication
The following steps outline how to generate a basic authentication API key:
Important
To generate a basic authentication API key, ensure that you have administrator access to the Lemonway Dashboard. If you do not have access please contact our onboarding team: [email protected]
-
Sign in to the Lemonway Dashboard using your credentials provided by our onboarding team
-
Select DEVELOPERS from the menu
-
Select API Keys from the listed options. This displays the API Keys generation page
-
Click GENERATE AN API KEY
-
Enter your Lemonway Dashboard password then, click GENERATE AN API KEY
-
To view the generated API key, click the padlock icon, then re-enter your password and click CONFIRM
-
Click the clipboard icon to copy your password. You will need this in Step 2
Note
API keys are generated and managed by the Lemonway Dashboard. They have an unlimited lifespan. If you suspect unauthorized use of an API key, you should immediately revoke it using the Lemonway Dashboard.
Step 2: Requesting an Access Token from the Authorization Server
You can make a POST request using your preferred tool.
Previously, we also offered the option to make the request using our Swagger UI for testing purposes. This method has been removed for the time being.
Two input keys are required to receive a successful HTTP (200) response:
| Key (Name) | Value | Field | Required Input | Description |
|---|---|---|---|---|
| Authorization | string | Header | Ensure that you enter the prefix basic, then paste the generated API Key. | The API Key that you copied from the Lemonway Dashboard in Step 1. |
| Example: basic da012c0f-b1a7-4f86-8279-3cd69b9185e2 | ||||
| Used to establish Client Authentication with the Authorization Server. | ||||
| Grant_type | string | Body | Enter the following Grant_type: client_credentials | Client credentials are a grant type that returns an Access Token of Bearer type. |
| forData | A bearer-type token uses HTTPS security. This is an authenticated token and is secure. |
If you prefer to use cURL, you can copy the example displayed, however, you must change the following parameters:
-
X POST URL + [endpoint] point to either the sandbox (https://sandbox-api.lemonway.fr/oauth/api/v1/oauth/token) or prod environment (https://auth.lemonway.com/oauth/api/v1/oauth/token)
-
H Authorization (basic + paste your API key)
Example: cURL
curl -X POST "https://sandbox-api.lemonway.fr/oauth/api/v1/oauth/token" -H "accept: application/json;charset=UTF-8" -H "Authorization: basic da012c0f-b1a7-4f86-8279-3cd69b9185e2" -H "Content-Type: application/x-www-form-urlencoded" -d "Grant_type=client_credentials"
A Successful Response from the Authorization Server
If the Client Authentication is successful the following output (with unique values) is displayed:
{
"token_Type": "Bearer",
"access_token": "e0cbc05f-8379-410f-9bx2x-68c94f1536e2",
"expires_in": 7776000
}
Important
The expires_in value displayed is in seconds: 7776000 (90 days). If your token expires, you will be required to POST another request using the same (initial) basic API key to create a new Bearer token.
Important
You do not need to create a new token for each API call. Create one token only, when the token expires, replace it using the method described in this document.
Testing your Bearer Token
Important
Always test in the sandbox environment before deploying to production.
Note
You will have to create a separate bearer token if you want to work in production.
To validate your Bearer token authentication start testing with the Lemonway REST API. Create accounts in the Lemonway Dashboard sandbox environment and get started.
HTTP Response Status Codes, Examples, and Potential Solutions
Here are some of the most common response status codes with examples and solutions to help you troubleshoot.
| HTTP Reponse Status Codes | Description | Example | Potential Solutions |
|---|---|---|---|
| 400 | Bad Request: The Authorization Server is unable to process the request due to an error. | The incorrect syntax has been used | Potential Solution 1: Review and confirm that the API key and Grant_type are correct. Go to the Lemonway Dashboard, copy and paste the API Key in notepad (or an alternative tool). Compare this API key with the one you are using to authenticate. |
| Alternatively, delete your current API key and paste another (a fresh) copy key in the POST field. | |||
| Potential Solution 2: Review and confirm that the Key (name) and Value (string) are in their correct fields. | |||
| Grant_type - formData | |||
| 401 | Unauthorized: The sent request is not authenticated with the Authorization Server. | The API key (Client Authentication) is not considered valid on the Authorization Server. Therefore no Access Token is delivered. | Potential Solution 1: Review and confirm that the API key and Grant_type are correct |
| Potential Solution 2: Check that your organization does not have any inward or outward-bound firewall restrictions. | |||
| Potential Solution 3: Contact Lemonway to confirm that your IP address is whitelisted | |||
| 404 | Not Found: This indicates that the sent request was unable to communicate with the Authorization Server. | Your internet is down | Potential Solution 1: Check that your internet connection is up and running. |
| or | Potential Solution 2: Check that your organization does not have any outward-bound firewall restrictions. | ||
| Firewall issue | Potential Solution 3: Report this to Lemonway support and we will resolve this issue as soon as possible. | ||
| 500 | Internal Server Error: Indicates that there is a problem or fault with the Authorization Server. | An unexpected software or hardware error on the server. | Potential Solution: Immediately report to Lemonway support and we will resolve this issue as soon as possible. |
Authorization Server response scenarios in relation to Bearer tokens
Here are some of the most common Authorization Server responses in relation to Bearer tokens.
| Scenario | Authorization Response |
|---|---|
| If the Bearer token does not exist | A new Bearer token is issued by the Authorization Server with a default expiration of 90 days. |
| If the Bearer token already exists | The remaining Bearer token expiration time is displayed. |
| Note: Bearer token time is displayed in seconds. The default expiration time is 90 days. | |
| If the Bearer token has expired | A new Bearer token is created and the old token is deleted. |