持久访问令牌

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 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 下方.

Creating an 访问令牌

Request

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

Request Body

The request body is a JSON object with the format detailed 下方.

In this example, the creation and persistence of an 访问令牌 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 w此处 an expiration date is desired, the request body should be as detailed 下方, w此处 an expiration field is added representing the moment when the 访问令牌 should expire.

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

Request Body Fields

(*) The permissions and privileges that the created 访问令牌 possesses are inherited from the permissions and privileges of the user whose credentials are included in the request. T此处fore, if the 访问令牌 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 访问令牌 as well as additional data about its expiration, the associated client identifier (see Deleting an 访问令牌), 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
            }
        }
    }
}

重要说明 Considerations

The following exception scenarios may arise when 使用 API based on the following possible conditions of use.

Duplicate description

Two consecutive 访问令牌 creation requests with identical content in the 说明 field of the JSON object sent in the request will cause the request to fail.

Repeated incorrect credentials

If three consecutive requests to the 访问令牌 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 访问令牌

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

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 下方.

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 访问令牌

As an example, 下方 are some of the services that can be used with an 访问令牌 created by this API:

1-/services/gear/仪表盘Service.svc/Get仪表盘

2-/services/core/警报Service.svc/Get提醒

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

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

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