Persistent Access Tokens
This API allows obtaining a token with administrator permissions, defining its lifetime.
Once generated, these tokens allow the invocation of various Back End Platform service APIs, enabling their use during the validity period of the obtained token.
Theory of operation
When integration of platform services is required by external applications, accessing these services requires obtaining a token known as an Access Token.
Access to and use of Platform services may be needed on a permanent or temporary basis.
The Platform's Authorization service includes two APIs for obtaining and deleting persistent tokens for these integration scenarios, detailed below.
Creating an Access Token
Request
POST /services/gear/AuthorizationService.svc/CreateClientAccessTokenAllIntegrations
Host: gear.cloud.studioRequest Body
The request body is a JSON object with the format detailed below.
In this example, the creation and persistence of an Access Token is requested without specifying an expiration date, which in this case will default to 01/01/2099.
}
"clientAccessToken": {
"Description": "Testing 10",
"ClientID": 79
},
"login": {
"LoginType": 1,
"Email": "xxxxx.xxxxxxx@cloud.studio",
"Password": "xxxxxxxxxxx"
}
}For cases where an expiration date is desired, the request body should be as detailed below, where an expiration field is added representing the moment when the Access Token should expire.
{
"clientAccessToken": {
"Description": "Testing 10",
"ClientID": 79
},
"login": {
"LoginType": 1,
"Email": "xxxxxx.xxxxxx@cloud.studio",
"Password": "xxxxxxxxx"
},
"expiration": 3600
}Request Body Fields
| Name | Description | Mandatory |
|---|---|---|
| Description | User-defined description generally detailing the purpose of the Access Token to be created, with a maximum of 255 characters. Unicode is supported. | Yes |
| clientID | Corresponds to the client identifier for which the token will be created. | Yes |
| LoginType | This field must contain the value 1, mandatorily. | Yes |
| Corresponds to the email of the account used to request the Access Token creation (*). | Yes | |
| Password | Corresponds to the password of the account used for the Access Token creation. | Yes |
| expiration | Corresponds to the time in minutes that the Access Token should be valid from the moment of its creation. | Yes |
(*) The permissions and privileges that the created Access Token possesses are inherited from the permissions and privileges of the user whose credentials are included in the request. Therefore, if the Access Token needs to have the same permissions as a platform administrator, the user used to execute the API must have such privileges.
Response
The response for a correctly processed request will return an HTTP status code of 200 and contains the created Access Token as well as additional data about its expiration, the associated client identifier (see Deleting an Access Token), and the submitted description.
{
"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
}
}
}
}Important Considerations
The following exception scenarios may arise when using the API based on the following possible conditions of use.
Duplicate description
Two consecutive Access Token creation requests with identical content in the Description field of the JSON object sent in the request will cause the request to fail.
Repeated incorrect credentials
If three consecutive requests to the Access Token creation API are sent with incorrect credentials for the Email / Password pair, the request will fail and the response will contain the error message "Please complete the captcha".
If this situation occurs, it can be resolved by logging into the Platform front-end and performing the login operation with the correct Email and Password combination. In this case, Captcha validation will be requested.
Once the Captcha is correctly validated and the platform is successfully accessed, the API can be retried.
Deleting an Access Token
Request
POST /services/gear/AuthorizationService.svc/DeleteClientAccessToken
Host: gear.cloud.studioRequest Body
{
"accessToken": "99a4d0a4-932d-468b-9c17-49b5afdffb0d",
"clientAccessTokenID": 14
}Request Body Fields
| Name | Description | Mandatory |
|---|---|---|
| accessToken | Previously created Access Token to be deleted. | Yes |
| clientAccessTokenID | Client identifier associated with the Access Token to be deleted. | Yes |
Response
The response for a correctly processed deletion request will return an HTTP status code of 200 and an empty body. A response with an HTTP status code of 500 should be considered a failed request and will contain a body as detailed below.
Response body for a successful deletion request and response body for a failed request:
{}{
"Exception": {
"ClassName": "ServiceException",
"FaultCode": "8001",
"FaultData": "",
"Message": "The access token is invalid or it doesn't have sufficient permissions to execute the requested operation"
}
}Platform services and their respective APIs that can be used with persistent Access Tokens
As an example, below are some of the services that can be used with an Access Token created by this 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