OAuth Authentication

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.

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

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

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:

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

  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.

Authorization Server response scenarios in relation to Bearer tokens

Here are some of the most common Authorization Server responses in relation to Bearer tokens.