Documentation technique - OAuth GetLandy

Principe de l'OAuth2 - Authorization Code

Mécanisme d'autorisation permettant à une application d'accéder à vos données GetLandy de manière automatique.

Un jeton (access token) est généré lors de de l'enregistrement et l'autorisation d'une application.

Ce jeton permettra à l'application d'accéder à vos données sur GetLandy de manière autonome et sécurisée.

Etapes du processus d'autorisation :

  1. authorize : vous demandez à l'application de lancer un processus d'autorisation
  2. login : le serveur OAuth vous redirige vers une page de login GetLandy
  3. authorize : le serveur d'OAuth vous demande confirmation de l'autorisation de l'application à accéder à vos leads GetLandy
    A ce stade, si tout s'est bien passé, l'application a récupéré un "Authorisation Code" qui lui permettra de demander un "Access Token"
  4. access_token : l'application peut contacter le serveur d'OAuth pour demander un jeton (Access Token) à partir du code récupéré précédemment
    et obtient en même temps un "Refresh Token"
  5. refresh_token : les jetons ont une durée de vie limitée (1 heure), passé ce délai, l'application peut demander un nouveau jeton à l'aide du "Refresh Token"

Prérequis

Endpoint : https://oauth.getlandy.com/authorize - Type GET

Paramètres d'appel

Obligatoire Nom Valeur Description
Oui response_type code chaine fixe
Oui client_id <GetLandyClientId> Code généré dans GetLandy lors de l'activation de l'api
Oui client_secret <GetLandyClientSecret> Code généré dans GetLandy lors de l'activation de l'api
Oui redirect_uri <url> Url de l'application traitant le retour du serveur d'OAuth (enregistrement access token)
Oui scope leads Périmètre d'autorisation (uniquement leads disponible)
Non state <csrf_token> Token CSRF généré par l'application, envoyé au serveur d'OAuth et vérifié au retour de la demande de jeton

Réponses

Authentification sur https://oauth.getlandy.com/ - Format <HTML>

Formulaire d'authentification utilisateur, puis formulaire de confirmation d'autorisation, puis retour vers l'url redirect_uri

Nom Valeur Description
code <authorization_code> Le code d'autorisation à transmette pour la demande d'Acces Token
state <csrf_token> Le token CSRF envoyé, pour vérification coté application

Compte GetLandy non trouvé - Format <HTML>

Message d'erreur

Paramètres incorrects ou manquants - Format <HTML>

Message d'erreur

Endpoint : https://oauth.getlandy.com/access_token - Type POST

Paramètres d'appel

Obligatoire Nom Valeur Description
Oui grant_type authorization_code chaine fixe
Oui client_id <GetLandyClientId> Code généré dans GetLandy lors de l'activation de l'api
Oui client_secret <GetLandyClientSecret> Code généré dans GetLandy lors de l'activation de l'api
Oui redirect_uri <url> Url de l'application traitant le retour du serveur d'OAuth (enreigstrement access token)
Oui code <authorization_code> Code d'autorisation retourné par le serveur OAuth

Réponses

Access Token généré - Format <JSON>

Access Token et Refresh Token générés et utilisables par l'application

Nom Valeur Description
token_type Bearer Type de token, chaine fixe
expires_in <int> TTL du token en secondes
access_token <string> Token signé par le serveur d'OAuth
refresh_token <string> Token permettant la demande d'un nouveau Access Token une fois celui ci expiré

Paramètres incorrects ou manquants - Format <JSON>

Message d'erreur

Nom Valeur Description
error <string> Message d'erreur

Endpoint : https://oauth.getlandy.com/refresh_token - Type POST

Paramètres d'appel

Obligatoire Nom Valeur Description
Oui grant_type refresh_token chaine fixe
Oui refresh_token <string> Refresh Token fourni lors de la demande d'Access Token
Oui client_id <GetLandyClientId> Code généré dans GetLandy lors de l'activation de l'api
Oui client_secret <GetLandyClientSecret> Code généré dans GetLandy lors de l'activation de l'api
Non scope leads Périmètre d'autorisation (uniquement leads disponibles)

Réponses

Access Token généré - Format <JSON>

Access Token et Refresh Token générés et utilisables par l'application

Nom Valeur Description
token_type Bearer Type de token, chaine fixe
expires_in <int> TTL du token en secondes
access_token <string> Token signé par le serveur d'OAuth
refresh_token <string> Token permettant la demande d'un nouveau Access Token une fois celui ci expiré

Paramètres incorrects ou manquants - Format <JSON>

Message d'erreur

Nom Valeur Description
error <string> Message d'erreur

Endpoint : https://oauth.getlandy.com/me - Type GET/POST

Utilisé pour tester si un token est actif et valide (et accessoirement récupérer les informations de l'utilisateur et du compte GetLandy)

HTTP Header : "Authorization: Bearer <Access_Token>"

Réponses

Access Token valide et actif - Format <JSON> - HTTP 200

Access Token valide, on retourne les informations concernant ce Token :

Nom Valeur Description
account <string> Nom du compte GetLandy pour lequel le token est actif
user <string> Email de l'utilisateur ayant validé l'autorisation d'accès à l'API

Access Token invalide ou révoqué - HTTP 401

Aucun retour autre que le code HTTP 401 (accès interdit)