AUTHENTICATION

This section will detail how to authenticate to the Somfy API in order to get an access token that will allow you to perform actions through the Somfy API.

First step is to create your own client application of the Somfy API providing a name and valid Redirect URIs.

Then, you can use the following section to generate a valid access token using the Consumer key and Consumer secret generated.


OAuth 2

Authorization is performed by OAuth2, « Authorization Code Grant » method is implemented.

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server. Detailed specification here.

     +----------+ 
     | Resource | 
     |   Owner  | 
     |          | 
     +----------+ 
          ^ 
          | 
         (B) 
     +----|-----+          Client Identifier      +---------------+ 
     |         -+----(A)-- & Redirection URI ---->|               | 
     |  User-   |                                 | Authorization | 
     |  Agent  -+----(B)-- User authenticates --->|     Server    | 
     |          |                                 |               | 
     |         -+----(C)-- Authorization Code ---<|               | 
     +-|----|---+                                 +---------------+ 
       |    |                                         ^      v 
      (A)  (C)                                        |      | 
       |    |                                         |      | 
       ^    v                                         |      | 
     +---------+                                      |      | 
     |         |>---(D)-- Authorization Code ---------'      | 
     |  Client |          & Redirection URI                  | 
     |         |                                             | 
     |         |<---(E)----- Access Token -------------------' 
     +---------+       (w/ Optional Refresh Token) 

Request authorization

A fresh token must be generated to be able to perform API calls. The token can be requested by redirecting the resource owner user agent to the following authentication server endpoint:

https://accounts.somfy.com/oauth/oauth/v2/auth?response_type=code&client_id=YOUR_CONSUMER_KEY&redirect_uri=https%3A%2F%2Fyour-domain.com%2Fsomewhere&state=YOUR_UNIQUE_VALUE&grant_type=authorization_code

A successful authorization will pass the client the authorization code in the URL via the supplied redirect_uri:

https://your-domain.com/somewhere?code=CODE_GENERATED_BY_SOMFY&state=YOUR_UNIQUE_VALUE

Once this is done, a token can be requested using the authorization code (this code has a short life validity time):

https://accounts.somfy.com/oauth/oauth/v2/token?client_id=YOUR_CONSUMER_KEY&client_secret=YOUR_CONSUMER_SECRET&grant_type=authorization_code&code=CODE_GENERATED_BY_SOMFY&redirect_uri=https%3A%2F%2Fyour-domain.com%2Fsomewhere&state=YOUR_UNIQUE_VALUE

If all went well, you will get a response like this:

{ 
"access_token": "*************************************************************", 
"expires_in": 3600, 
"token_type": "bearer", 
"scope": "**** **** ****", 
"refresh_token": "************************************************************" 
}

Refreshing an expired access_token

To get a new access token, the refresh token is needed. The refresh_token will be valid 14 days.

https://accounts.somfy.com/oauth/oauth/v2/token?client_id=YOUR_CONSUMER_KEY&client_secret=YOUR_CONSUMER_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

After a token has been granted to your application, you can call the API endpoints described in the APIs documentation.