Do you need Help? Look for your answers among the Frequently Asked Questions.


help What is the Works with Legrand program?

Works with Legrand is an open interoperable platform, a strategic part of Eliot, the Legrand innovative program dedicated to promoting the design and deployment of Legrand connected devices. The program allows the Legrand ecosystem to be compatible with major IoT global players. Works with Legrand, thanks to important partnerships, breaks boundaries enabling other companies to connect their devices or services with Legrand products.

help What is the price for using this service?

For a standard usage, this service does not cost anything. You just have to create an account, subscribe to the Starter Kit and enjoy!

help Why could I be interested in this program?

The program is an open approach to enable innovation for living and working spaces; if you are integrating our solutions or if you want to enable services based on data coming from Legrand devices, this is the right place. Develop your solution and start to be part of our community!

help How can my company become part of Legrand's partners?

You can consume Legrand APIs free of charge, after the sign-in, but with some limitations on the number of calls. If you want to become part of our connections or if you need to increase the number of permitted calls, you need to go in the Contact page and send us an email. We will receive your request and we will contact you as soon as possible!

help I've developed a solution. How can I be part of the solution showcase?

Thanks to be part of our community! You can share your solution with us using the Contact page and send us an email. Fill in all the request and we will contact you as soon as possible

help How can I access the forum?

Your developper account can also be used on the forum. Sign-In and click on "Forum" in the menu. You can manage your personnal information in the Profile menu.

help How can I test the APIs?

Go on the drop down menu "APIs" and choose "APIs list". Click on the API you want to start your tests.

help What do I need to do to start creating an application ?

Go on the drop down menu "APIs" and choose "Subscriptions". For further information, you can consult our tutorials.

Account management

help How can I register an account?

In order to access to data concerning the APIs, you need to create an account. Go on the Sign Up page.
If you are a third party developer / partner, you have to click on the Sign Up of "You are a developer?" and start filling all the form.

If you are an internal developer, choose the Legrand's Sign in.

help How can I change my credentials?
To change your credential (email, First name and Surname) you need to Sign In click on the Profile menu and choose "Change Account Information".
Once you have clicked there you will see the page depicted in the image.
Change the field you want and insert the password to confirm this action.
Image of the change credential interface
help I've lost my password. What can I do?

Go in the Sign In page. Click on "Forgot your password ?" and follow the steps to get a new one

help How can I delete my account?
Once signed-in, go to your Profile. Click on "Close account" and validate.


help Is there any test accounts or devices?

Unfortunately, there are no test accounts or devices for the moment.

help Can I access data directly from the devices?

It is not possible. The only way to access the data and the devices is via the Cloud APIs.

help I've tried the API and I receive this error
Error CodeNameDescriptionPossible Solution
400Bad requestSomething is probably wrong in your request body or headerCheck your request body and header
401UnauthorizedUser is not authorized to access the requested resourceSign into Eliot cloud before sending your request

Check your product subscription

User is trying to access a resource on which he is not allowed : check that you are using right user credentials on right plant and device


403Operation forbidden or Quota exceededYour account is not authorized to access the requested resource or
out of call volume quota. Quota will be replenished in hh:mm:ss
Check if you have the requested permissions or wait for the suggested time to repeat your request
404Resource not found/Gateway offlineSomething is probably wrong in your request URL or your device is temporary disconnected from the networkCheck your request URL, including request parameters (API version, plant id, module id) or check your device connection
406Request not acceptableAcceptance header is invalid for this endpoint resourceCheck if the given parameters are valid
408Request timeoutThe server did not received a complete request within the server’s allotted timeout periodWait a few seconds and try to send your request again
430Wrong input parametersYour request body contains invalid valuesCheck the parameters of your values in your request body
469Official application password expiredPassword used in the Legrand or Bticino Thermostat app is expiredPlease renew user password through the application
470Official application terms and conditions expiredTerms and conditions for Legrand or Bticino Thermostat app are expiredPlease accept again terms and conditions through the application
486Busy visual user interfaceYour Legrand or Bticino thermostat device user interface has been used locallyWait about 10 seconds and try to send your request again
500Server internal errorThe server is not operationalWait for the server to work again
help Why there is a Primary key and a Secondary key in my subscription?

Both keys are usable, and only one key is needed at a time. Thanks to these 2 keys, you can change a key without down time of your application. For example, if you want to replace your primary key, the procedure is :

  • Configure your application to use the secondary key;
  • Deploy it to your customers;
  • Regenerate the primary key;
  • (optional) reconfigure your application to use the new primary key
help I am a third-party developer, how can I register a webhook?

In order to register a webhook for Home + Control API or Smarther API, follow the specific tutorial on the link

help What are user consents? Can it be revoked?

It is mandatory for users to accept the scopes defined in your application in order to use it. Users can revoke the consents they gave on a specific application from a Legrand app. This revokation process must not be implemented by third party applications.

help What happen if the user refuse the consents?

The user will have to consent on all the scopes provided during the application registration step. The user has 2 options:

Accept all scopes: in this case, Legrand authentication will resume and redirection to the reply URL will be made
Deny: if the user denies, he will not be connected, so he will have to log in again and consent on the scopes to access the application. Moreover, he will be redirected to the redirect_uri with two parameters in query string :

  • error: access_denied
  • error_description: Access denied by user
help What happens if I change the scopes required in my application?

You changed the scopes required by your application and this change has been approved. Then, the authentication will not be allowed as long as the scopes required on the previous refresh_token are different from the scopes currently existing on the application. You will need to ask for a new authentication with the grant_type "authorization_code", so the user can give his consent on the new provided scopes.

help How long a token is valid?
  • id_token = 1 hour
  • access_token = 1 hour
  • refresh_token = 90 days
help How can I retrieve my plantId, moduleId and ambientId?

To find the plantId

  • Sign up with your Works with Legrand account. You must have subscribed to the Starter Kit
  • Go on the “API” drop down menu, click on “APIS LIST” and choose the Smarther API or Home + Control API
  • On the left, click on “GET Plants” for the Smarther or “GET Get users’ plants” for Home + Control. Then go in the “Try it”
  • In Authorization section, choose “Authorization code” for ELIOT - Azure AD B2C - OpenID Connect for the Smarther or OAuth Server for Try it Eliot API for Home + Control. If you are logged in, other information are already filled up
  • A popup will be opened. Fill the information and validate
  • Click on “Send” button and retrieve the ID of the plant in the Response content


To find the moduleId and ambientId

  • Sign up with your Works with Legrand account. You must have subscribed to the Starter Kit
  • Go on the “API” drop down menu, click on “APIS LIST” and choose the Smarther API or Home + Control API
  • On the left, click on “GET Topology” for the Smarther or “GET Get plant’s topology” for Home + Control. Then go in the “Try it”
  • In the Query parameters, fill in the “plantId” field
  • In Authorization section, choose “Authorization code” for ELIOT - Azure AD B2C - OpenID Connect for the Smarther or “Authorization code” for OAuth Server for Try it Eliot API for Home + Control. If you are logged in, other information are already filled up
  • Click on “Send” button and retrieve the IDs of the modules and the ambient (only for Home + Control) in the Response content
help How can I associate my Smarther or C300X13E account to my WWL account?
  • First, if you don’t have a Legrand account you need to create one on Works with Legrand and to subscribe to the Starter Kit
  • You must also have downloaded the Thermostat or Door Entry application and to have created an other account (you can use the same Email/Password as previously)
  • On the left side menu, click on “Account” and then on “Third-party access”
  • Sign-in by using your Legrand credentials
  • A message will appear to confirm the connection. You can now use the APIs
  • To use the “Try it”, you need to enter your Legrand credentials
Illustration of linking Legrand's and Smarther's or C300X13E’s accounts


help What does the different terms means?

Eliot devices

PlantA locationA house, an apartment, …
AmbientA roomLiving room, bed room, …
(Ambient) ModuleA precise deviceMy first light, my second Céliane plug, …
(Ambient module’s) PlugAn individual plug in a roomThe plug of the house’s kitchen
DeviceA logical type of deviceLight, plug, lock, …
Device systemThe family to which the device belongEnergy management, lighting, …
GatewayThe device which is directly connected to the IoTHUBCéliane with Netatmo, Smarther, …



Oauth2 authentication process

JSON Web Tokens (JWT)It is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. It's used for authentication and information exchange
OpenID Connect protocolBuilt on top of the OAuth 2.0, it fills the gaps on missing security concerns. It adds a new type of token - which is called id_token - that can be seen as an id card of the user. The format of this token is strictly defined to be compliant to the JWT standard, which is to sum up a JSON formatted, base 64 encoded and signed token
Id token (id_token)An id_token cannot be used for API access. Each token contains information on the intended audience (recipient). According to the OpenID Connect specification, the audience (claim aud) of each id_token must be the client_id of the application making the authentication requesteyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI…
Access token (access_token)Access tokens are the thing that applications use to make API requests on behalf of a user. The access token represents the authorization of a specific application to access specific parts of a user’s dataeyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZ…
Refresh token (refresh_token)refresh token is a special kind of token that can be used to obtain a renewed access token —that allows accessing a protected resource— at any time. You can request new access tokens until the refresh token is blacklisted. Refresh tokens must be stored securely by an application because they essentially allow a user to remain authenticated forevereyJraWQiOiJjcGltY29yZV8wOTI1MjA…
ScopeOAuth 2.0 scopes provide a way to limit the amount of access that is granted to an access token. For example, an access token issued to a client app may be granted READ and WRITE access to protected resources, or just READ access. You can implement your APIs to enforce any scope or combination of scopes you wish. So, if a client receives a token that has READ scope, and it tries to call an API endpoint that requires WRITE access, the call will failGet the state of plugs (plug.read), Control plugs (plug.write), Change comfort parameters (temperature setpoint,…) (comfort.write)


Application ID (client_id)It is the unique authentication code of your application. You can find it in “My applications” by clicking on “Details”3dd29288-cy59-41fa-b492-d8f8289149e7ed


Client secret (client_secret)It is a unique code sent by email at the approval of your application. You must keep it preciously because it can’t be sent back to youp+.3tog736W52,f~73P3Dt2r
User consentIn order to use your application, the user must approve the scopes you defined. User consents are asked just once on the first connection, or each time you change the scopes