Tutorials

OAuth2 end-point url

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:

Simplified diagram of the flow


Step 1 : Authorization end-point

 

Request

This flow must be done only once, during account linking. After that, you must use /token flow periodically to get and refresh access_token.

 

Nota:

You can find the different endpoints at the following URL : https://login.eliotbylegrand.com/0d8816d5-3e7f-4c86-8229-645137e0f222/v2.0/.well-known/openid-configuration?p=B2C_1_Eliot-SignUpOrSignIn

 

Make a GET request to:

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

 

With the following parameters:

Parameter namePresenceValue
client_idmandatoryClient_id received by mail
redirect_urimandatorySpecified redirect_uri (exactly the same)
response_typemandatoryValue is “code”
staterecommendedA 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.

 

Step 2 : Token end-point

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

 

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 namePresenceValue
client_idmandatoryClient_id received by mail
grant_typemandatoryValue is “authorization_code”
codemandatoryValue is the code you retrieve from the /authorize flow before
client_secretmandatoryclient_secret received by email

 

Answer

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

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

 

Step 3 : 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 namePresenceValue
client_idmandatoryclient_id received by mail
grant_typemandatoryValue is “refresh_token”
refresh_tokenmandatoryValue is the refresh_code you retrieve from the /token flow described just before or from this flow
client_secretmandatoryclient_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 use 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 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.

 

Nota:

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


Possible errors you can get when using authorization flow

 

Error codeNameDescriptionPossible solution
400invalid_requestThe request is malformed, a required parameter is missing or a parameter has an invalid valueCheck all your parameters and their spelling
unauthorized_clientThe client is not authorizedCheck your client_id parameter
access_deniedThe resource owner denied the request for authorizationCheck if your authentication information match with your Works With Legrand account
unsupported_response_typeUnsupported response typeCheck your grant_type parameter
invalid_scopeThe scope is malformed or invalidIf you defined custom scopes, check if they are valid  or well spelled
server_errorThe 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_unavailableThe authorization server is not able to handle the requestCheck the server status and your parameters
401invalid_clientThe client_id doesn't existCheck your client_id parameter
500server_errorAn unexpected server error occuredWait for the server to work again
/Could not get any responseThe server couldn't send a response
  • Ensure that the server is working properly
  • Check if you misspelled the server URL