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.
You can see here a simple sequence diagram:
This flow must be done only once, during account linking. After that, you must use /token flow periodically to get and refresh access_token.
You can find the different endpoints at the following URL : https://partners-login.eliotbylegrand.com/[client_id]/.well-known/openid-configuration
Make a GET request to:
https://partners-login.eliotbylegrand.com/authorize
With the following parameters in query string:
| Parameter name | Presence | Value |
|---|---|---|
| client_id | mandatory | Client_id received by mail |
| redirect_uri | mandatory | Specified redirect_uri (exactly the same) |
| 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/
The server returns a code, used with the token end-point.
This end point is used to get and refresh the access_token.
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 in the body:
| 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 |
The server returns a JWT, containing at least the following elements:
As the access_token is valid one hour, you must refresh it regularly.
Make a POST request to:
https://partners-login.eliotbylegrand.com/token
With the following parameters in the body:
| 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 |
As from the preceding flow, the server returns a JWT, containing at least the following elements:
The received refresh_token changes at each request. In order to be valid lifetime, you have to use the new generated refresh_token code to refresh your access_token.
If there is no connection to your application during more than 90 days, your token will expire and you will have to renew your Oauth2 token flow
| Error code | Name | Description | Possible solution |
|---|---|---|---|
| 400 | invalid_request | The request is malformed, a required parameter is missing or a parameter has an invalid value | Check all your parameters and their spelling |
| unauthorized_client | The client is not authorized | Check your client_id parameter | |
| access_denied | The resource owner denied the request for authorization | Check if your authentication information match with your Works With Legrand account | |
| unsupported_response_type | Unsupported response type | Check your grant_type parameter | |
| invalid_scope | The scope is malformed or invalid | If you defined custom scopes, check if they are valid or well spelled | |
| server_error | The authorization server encountered an unexpected condition that prevented it from fulfilling the request. This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client by an HTTP redirect. | Check your parameters and the server status | |
| temporarily_unavailable | The authorization server is not able to handle the request | Check the server status and your parameters | |
| 401 | invalid_client | The client_id doesn’t exist | Check your client_id parameter |
| 500 | server_error | An unexpected server error occured | Wait for the server to work again |
| / | Could not get any response | The server couldn’t send a response | Ensure that the server is working properly Check if you misspelled the server URL |