Tutorials

This section contains all documentation usefull to use our API.

To get started with Works with Legrand, follows this tutorial. After you complete this guide, you will have a Works with Legrand developer account (congratulation!) and you will be able to try our APIs included in the Starter Kit plan.

Step 1 : Create an account

You must Sign-Up to create your account. Thanks to this account, your are now known as a developer within Works with Legrand portal. If you already have a developer account, you just have to Sign-In.

Nota

With this account, you also will be able to use ours (and yours) applications as an “end-user”, but if you already have an “end-user” account, you cannot use it to sign-in within Works with Legrand portal.


Step 2 : Subscribe to a product and get subscription key

You need to subscribe to a product to use APIs. When you subscribe to a product, you could use APIs associated to the product.
Go to the Products page to see available products.

Product link on main navigation

For now, there is one product, Starter Kit, available for free. This product contains all APIs dedicated for 3rd parties, with a limitation on 100 calls per day.
When you click on the product name, you see the list of APIs available, and you can subscribe to the product.

Starter kit link on main navigation

Once you subscribed to an API, you are redirected to your profile account page, where are listed all your subscription:

Subscription details

Primary key and Secondary key are unique per subscription and per account. You have to use it into your application to identify your subscription (Ocp-Apim-Subscription-Key parameter in the header of the HTML request).


Step 3 : Try-it!

You can test the API directly within Works with Legrand portal.
On the following example, we use the Echo API, a simple API dedicated to test, which does not needs a real device to work. To proceed, choose the Create resource of Echo API and then click on Try it:

Echo API

Concerning this API, and also concerning all our APIs, there are 2 mandatory parameters to put in HTML header:

  • Authorization and Ocp-Apim-Subscription-key is directly filled by the portal. It corresponds to the Primary key or the Secondary key of the API linked to your account.
  • Authorization is the token sent by the user manager service. To get it, select Authorization code in the Authorization section:
    Authorization section

It opens a sign-in windows, where you must enter your credential linked to your LEGRAND account (developer or end-user account). It automatically fills the Authorization field in the header with the right token:

 Authorization field

After that, you can send the message by clicking on Send at the bottom of the page:

Send button

You will get the answer, with the response status, the latency and the response content:

Response content


To successfully create an application with Works with Legrand, follow this step-by-step tutorial.
Before you begin, be sure to complete the Getting Started tutorial, where you'll get your LEGRAND developer account, a subscription key, and learn how to explore APIs.

Step 1 : Register your application

To use our APIS, first register your application to obtain its unique set of credentials, which your users will use to enable your app to access their data.

1. Go to My Applications, a page dedicated to application management.

Go to My Application


2. Then click on Create New and fill all followings fields:

Register new application form

Fields Name, Description, Vendor and Logo will be displayed to end-user when he will give the consent for the application to access to his data.
Url field corresponds to the web site where users can learn more about your application.
Reply Url field is use to redirect users back to your application during the authorization process. This corresponds to Oauth2 standard flow.

Important

When your application requests authorization to access a user's data, it includes a redirect_uri parameter in its query string. To authorize your application, this value must match exactly against of URL you provide, including any trailing slashes.


Step 2 : Check scopes

Before validating the application, you also need to specify which scope you need to use with your application:

Scopes checklist

Required scopes are details in description of each API description.
And then you could save at the end of the page.


Step 3 : Getting application details

Once you ask to register your application, you will receive an email that contains all information useful to use your application: client_id and client_secret.


0auth2

Our authentication mechanism is a standard Oauth2 one. It follows Oauth2 standard and a lot of documentation can be found on internet. For example, you could find documentation on Microsoft site.


Authorization end-point

Request

This flow must be done only once, during account linking. After that, you must used /token flow periodicaly to get and refresh access_token. This flow needs a GET request to

https://partners-login.eliotbylegrand.com/authorize

With the following parameters:

Parameter name Presence Value
client_id mandatory Client_id received by mail
redirect_uri mandatory Specified redirect_uri (exactly the same, with trailing slashes)
response_type mandatory Value is “code”
state recommended A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross-site request forgery attacks.

Example of request:


https://partners-login.eliotbylegrand.com/authorize?
client_id=7700d7f4-b48e-4452-b493-5d14b45ef47e
&response_type=code
&state=d8cdccaa-0c37-4493-ab37-d5d92bc99cd7
&redirect_uri=https://www.mycompany.com/callback/ 

Answer

The server returns a code, used with the token end-point.


Token end-point

This end point is used to get and refresh the access_token.

Authorization code flow

Request

To get the access_token (which must be add to the request each time you call an API), you must make a POST request to

https://partners-login.eliotbylegrand.com/token

With the following parameters:

Parameter name Presence Value
client_id mandatory Client_id received by mail
grant_type mandatory Value is “authorization_code”
code mandatory Value is the code you retrieve from the /authorize flow before
client_secret mandatory client_secret received by email
Answer

The server returns a JWT, containing at least the following elements:

  • An access_token: used each time you used an API for authorization (valid one hour)
  • A refresh_token: used to refresh the access token before its expiration (valid 90 days).


Refresh token flow

As the access_token is valid one hour, you must refresh it regularly.

Request

Make a POST request to

https://partners-login.eliotbylegrand.com/token

With the following parameters:

Parameter name Presence Value
client_id mandatory client_id received by mail
grant_type mandatory Value is “refresh_token”
refresh_token mandatory Value is the refresh_code you retrieve from the /token flow described just before or from this flow
client_secret mandatory client_secret received by email
Answer

As from the preceding flow, the server returns a JWT, containing at least the following elements:

  • An access_token: used each time you used an API for authorization (valid one hour)
  • A refresh_token: used to refresh the access token before its expiration (valid 90 days).
The received refresh_token have to be store to be used later to get a new access_token.