Tokens d'accès persistants

Cette API permet d'obtenir un token disposant de permissions d'administrateur, en définissant sa durée de vie.

Une fois générés, ces tokens permettent d'invoquer diverses API des services Back End de la plateforme, et peuvent être utilisés pendant toute la période de validité du token obtenu.

Principe de fonctionnement

Lorsque des applications externes doivent intégrer les services de la plateforme, l'accès à ces services nécessite l'obtention d'un token appelé token d'accès (Access Token).

L'accès aux services de la plateforme et leur utilisation peuvent être nécessaires de manière permanente ou temporaire.

Le service d'autorisation de la plateforme comprend deux API permettant d'obtenir et de supprimer des tokens persistants pour ces scénarios d'intégration, décrites ci-dessous.

Création d'un token d'accès

Requête

POST /services/gear/AuthorizationService.svc/CreateClientAccessTokenAllIntegrations
Host: gear.cloud.studio

Corps de la requête

Le corps de la requête est un objet JSON au format décrit ci-dessous.

Dans cet exemple, on demande la création et la persistance d'un token d'accès sans préciser de date d'expiration ; dans ce cas, celle-ci sera par défaut le 01/01/2099.

}
    "clientAccessToken": {
        "Description": "Testing 10",
        "ClientID": 79
    },
    "login": {
        "LoginType": 1,
        "Email": "xxxxx.xxxxxxx@cloud.studio",
        "Password": "xxxxxxxxxxx"
    }
}

Si l'on souhaite définir une date d'expiration, le corps de la requête doit être tel que décrit ci-dessous, avec un champ expiration supplémentaire représentant le moment où le token d'accès doit expirer.

{
    "clientAccessToken": {
        "Description": "Testing 10",
        "ClientID": 79
    },
    "login": {
        "LoginType": 1,
        "Email": "xxxxxx.xxxxxx@cloud.studio",
        "Password": "xxxxxxxxx"
    },
    "expiration": 3600
}

Champs du corps de la requête

(*) Les permissions et privilèges du token d'accès créé sont hérités des permissions et privilèges de l'utilisateur dont les identifiants figurent dans la requête. Par conséquent, si le token d'accès doit disposer des mêmes permissions qu'un administrateur de la plateforme, l'utilisateur qui exécute l'API doit posséder ces privilèges.

Réponse

La réponse à une requête correctement traitée renvoie un code de statut HTTP 200 et contient le token d'accès créé, ainsi que des données supplémentaires sur son expiration, son identifiant client associé (voir Suppression d'un token d'accès), et la description envoyée.

{
    "CreateClientAccessTokenAllIntegrationsResult": {
        "AccessToken": "8e15e6d1-821a-4b71-a78d-8338e3307d2b",
        "ClientAccessTokenID": 214,
        "ClientID": 79,
        "DateTimeCreated": {
            "Date": {
                "Day": 16,
                "Month": 12,
                "Year": 2022
            },
            "Time": {
                "Hour": 18,
                "Millisecond": 660,
                "Minute": 38,
                "Second": 33
            }
        },
        "Description": "German Prueba 1",
        "ExpirationDateTime": {
            "Date": {
                "Day": 1,
                "Month": 1,
                "Year": 2099
            },
            "Time": {
                "Hour": 0,
                "Millisecond": 0,
                "Minute": 0,
                "Second": 0
            }
        }
    }
}

Points importants

Les cas d'exception suivants peuvent survenir lors de l'utilisation de l'API, selon les conditions d'utilisation décrites ci-dessous.

Description en double

Deux requêtes consécutives de création de token d'accès dont le champ Description a un contenu identique dans l'objet JSON envoyé feront échouer la requête.

Identifiants incorrects répétés

Si trois requêtes consécutives sont envoyées à l'API de création de token d'accès avec des identifiants incorrects pour la paire Email / Password, la requête échoue et la réponse contient le message d'erreur "Please complete the captcha".

Dans ce cas, il suffit de se connecter au front-end de la plateforme et d'effectuer l'opération de connexion avec la bonne combinaison d'Email et de Password. Une validation Captcha sera alors demandée.

Une fois le Captcha correctement validé et l'accès à la plateforme réussi, l'API peut être appelée à nouveau.

Suppression d'un token d'accès

Requête

POST /services/gear/AuthorizationService.svc/DeleteClientAccessToken
Host: gear.cloud.studio

Corps de la requête

{
	"accessToken": "99a4d0a4-932d-468b-9c17-49b5afdffb0d",
    "clientAccessTokenID": 14
}

Champs du corps de la requête

Réponse

La réponse à une requête de suppression correctement traitée renvoie un code de statut HTTP 200 et un corps vide. Une réponse avec un code de statut HTTP 500 doit être considérée comme un échec et contient un corps tel que décrit ci-dessous.

Corps de la réponse à une requête de suppression réussie et corps de la réponse à une requête en échec :

{}

{
    "Exception": {
        "ClassName": "ServiceException",
        "FaultCode": "8001",
        "FaultData": "",
        "Message": "The access token is invalid or it doesn't have sufficient permissions to execute the requested operation"
    }
}

Services de la plateforme et API correspondantes utilisables avec des tokens d'accès persistants

À titre d'exemple, voici quelques-uns des services utilisables avec un token d'accès créé par cette API :

1-/services/gear/DashboardService.svc/GetDashboard

2-/services/core/AlarmService.svc/GetAlert

3-/services/gear/DeviceService.svc/CreateDeviceModel

4-/services/gear/DeviceService.svc/EditDeviceModel

5-/services/gear/DeviceService.svc/DeleteDeviceMod