Access Tokens Persistentes

Esta API permite obtener un token que tendrá permisos de administrador, definiendo el tiempo de vida del mismo.

Estos tokens una vez generados permiten la invocacion de distintas APIs de servicios del Back End de la Plataforma permitiendo su uso durante el tiempo de validez del token obtenido.

Teoría de operación

Cuando se requiere la integración de servicios de la plataforma por aplicaciones externas a ella, el acceso a los servicios requiere de la obtencion de un  token conocido como Access Token . 

El acceso y uso de los servicios de la Plataforma puede necesitarse en forma permanente o temporal.

El servicio de Autorizacion de la Plataforma incluye para estos esenarios de integracion dos API para la obtención y eliminación de Tokens persistentes  que se detallan a continuación.

Creación de un Access Token 

Request

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

Request Body 

El cuerpo del request sera un objeto JSON con el formato que se detalla a continuáción. 

En este ejemplo se solicita la creación y persistencia de un Access Token sin especificar su fecha de expiración la cual en este caso será equivalente a la fecha 01/01/2099 

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

En cambio, para los casos en dónde se desee determinar una fecha de expiración el cuerpo del request debe ser segun se detalla a continuación en donde se agrega un campo de nombre expiration que representa el momento en que se desea que el Access Token expire.

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

Request Body Fields

(*) Los permisos y privelegios que el Access Token creado posea son heredados de los permisos y privilegios del usuario cuyas credenciales se incluyen en el request por lo que si se desea que el Acess Token tenga los mismos permisos que un administrador de la plataforma el usurio a utilizarse en la ejecución de la API deberá tener tales privilegios.

Response

La respuesta en el caso de un correcto procesamiento del request retornará un código de estado de HTTP 200 y contiene el Access Token creado como asi tambien datos adicionales sobre la expiración del mismo el identificador de cliente asociado (ver Eliminación de un Access Token) y la descripción enviada.

{
    "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
            }
        }
    }
}

Consideraciones Importantes

Los siguentes escenarios de excepción pueden presentarse en el uso de la API en función de las siguentes y posibles condiciones de uso.

Descripción ya existente

Dos request consecutivos de creación de Access Token con idéntico contenido en el campo Description del objeto JSON enviado en el request provocara que este falle.

Repetición de credenciales incorrectas

En el caso de que se envien en los request de la API de creación de Access Tokens tres veces consecutivas credenciales y estas sean incorrectas para el par E-mail / Password el request fallará y en la respuesta se obtendrá el mensaje de error “Please complete the captcha”. 

De producirse esta situación se la puede resolver ingresando al front-end de la Plataforma y realizar la operación de log-in con la combinación de E-mail y Password correcto. En este caso se se solicitará que se valide el Captcha. 

Una vez  validado correctamente el Captcha y de ingresar correctamente a la plataforma se podrá reintentar el uso de la API. 

Eliminación de un Access Token

Request

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

Request Body

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

Request Body Fields

Response

La respuesta en el caso de un correcto procesamiento del request de eliminación retornará un código de estado HTTP 200 y un body vacio, una respuesta con código de estado HTTP 500 debe considerarse como un request fallado a su vez contendra un body como se detalla a continuacion.

Body de la respuesta de la correcta ejecución de un request de eliminacion para un Access Token y body de la respuesta en el caso de un request fallido

{}

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

Servicios y respectivas API de la Plataforma que se pueden utilizar con los Access Token persistentes

A modo de ejemplo se enumeran a continuacion algunos de los servicios que se pueden utilizar contando con un Access Token creado por esta 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