OAuth 2.0

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 further information, see OAuth 2.0 (External Website)

📘

Disclaimer

Lemonway is not responsible for the content displayed on external websites. Links to external websites are provided to help you with technical information that is outside the scope of this topic. Lemonway does not maintain or, control the content on these websites (unless otherwise stated).

📘

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.

These are the two steps:

  1. Generate a basic authentication API key using the Lemonway Dashboard. This step is required to establish Client Authentication with our Authorization Server.

  2. 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. If you do not have access to this application please contact a member of the sales team at [email protected]

📘

Note

To access the Lemonway Dashboard, use the sign-in credentials emailed to you by our onboarding team.

Alt TextAlt Text

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]

  1. Sign in to the Lemonway Dashboard using your credentials provided by our onboarding team

  2. Select DEVELOPERS from the menu

  3. Select API Keys from the listed options. This displays the API Keys generation page

  4. Click GENERATE AN API KEY

  5. Enter your Lemonway Dashboard password then, click GENERATE AN API KEY

  6. To view the generated API key, click the padlock icon, then re-enter your password and click CONFIRM

  7. 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 or by using our Swagger UI:

Prod version: OAuth POST method (Prod version)

Sandbox version: OAuth POST method (Sandbox version)

Two input keys are required to receive a successful HTTP (200) response:

Key (Name)ValueFieldRequired InputDescription
AuthorizationstringHeaderEnsure 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_typestringBodyEnter the following Grant_type: client_credentialsClient credentials is a grant type that returns an Access Token of Bearer type.
forDataA 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 or prod environment

  • 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 CodesDescriptionExamplePotential Solutions
400Bad Request: The Authorization Server is unable to process the request due to an error.The incorrect syntax has been usedPotential Solution 1: Review and confirm that the API key and Grant_type is 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
401Unauthorized: 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 is 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
404Not Found: This indicates that the sent request was unable to communicate with the Authorization Server.Your internet is downPotential Solution 1: Check that your internet connection is up and running.
orPotential Solution 2: Check that your organization does not have any outward-bound firewall restrictions.
Firewall issuePotential Solution 3: Report this to Lemonway support and we will resolve this issue as soon as possible.
500Internal Server Error: Indicates that there is a problem or falt 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.

ScenarioAuthorization Response
If the Bearer token does not existA new Bearer token is issued by the Authorization Server with the default expiration of 90 days
If the Bearer token already existsThe remaining Bearer token expiration time is display
Note: Bearer token time is displayed in seconds. The default expiration time is 90 days.
If the Bearer token has expiredA new Bearer token is created and the old token is deleted