OAuth Authentication with Lemonway

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.

📘
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 sign-in credentials emailed to you by the Lemonway onboarding team. If you do not have access to this application, please contact us at onboarding@lemonway.com

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: Onboarding Team

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 unauthorised 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.

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.

👍
One token for all calls
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

👍
Sandbox test first
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 Response 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.