Cloud APIs

Using mobile App or Cloud/device APIs

You can either use mobile app or directly invoke cloud APIs to connect and explore the device capabilities.

In general, Cloud API can be classified into two broad categories:

  • Device bound APIs exposed by services like VST, Metropolis microservices etc., running on the device

  • Cloud bound APIs implemented and supported by Cloud

Device bound API acts as a proxy that validates user identity and authorization, following which request is routed to the appropriate device. Cloud bound APIs do not interact with edge devices directly, and are mainly used for user management and device setup.

Accessing Cloud APIs

To access the cloud APIs, users must first connect to the IDP and authenticate and authorize themselves. As defined in the OpenID Connect specification, upon successful OAuth2 authentication, the IDP will return an id_token, or a JWT (JSON Web Token) security token. Users must include the id_token issued by the IDP in all their API requests to the cloud.

Token for cloud API access

In the reference implementation, cloud uses AWS Cognito as the default identity provider. This section provides steps to be followed to fetch the id_token while using AWS Cognito as IDP. Actual steps and API usage may vary based on your selection of IDP.

1. Get Access Token:

Sign up and sign in from a web console, to be authenticated. The sign up/in page URI is printed at the end of running the deployment script successfully. Copy and paste the URI into to your browser of choice. It should look something like this:

https://cognito.<domain-name>/login?redirect_uri=<redirect-uri>&client_id=<client-id>&response_type=code
../_images/cognito-signin.png

Once you are successfully signed in, get the authorization code issued while being redirected to the callback URI:

../_images/cognito-auth-code.png

2. Get id token from Access token:

Use the authorization code issued in Step:1 to get id_token or a JWT bearer token that can be eventually used to access cloud APIs. The token endpoint URI is printed at the end of running the deployment script successfully.

Below is the sample curl request to get id token from AWS Cognito:

curl GET https://cognito.<domain-name>/oauth2/token?grant_type=authorization_code&
code=<access token from step1>&
client_id=<client-id>&
redirect_uri=<redirect-uri>

Token for device API access

To access device APIs, users must first authorize with the reference cloud using the id_token issued by the IdP and exchange it for a special JWT (JSON Web Token) security token, or Authz token, that is specific to the device API. This Authz token, issued by the cloud, should be included in all API requests bound for the device.

curl -X GET  -H "Content-Type: application/json" -H "Authorization: Bearer <IDP_JWT_TOKEN" "https://<cloud_gateway_endpoint>/api/authorize?device_id=<device-id>"

Access Device APIs via cloud

Services running on the device, such as VST and Metropolis microservices, expose REST APIs. These APIs are collectively referred to as device APIs. End users can connect to and use all these device APIs via the cloud. For details of the REST endpoints exposed by the different services running on the device, refer to the documentation sections corresponding to each service. To access the device REST endpoints via cloud, the REST endpoint should be pre-fixed with the string “/proxy/”.

For example, to get the VST settings via cloud below is the updated REST endpoint:

"/proxy/vst/api/vst/settings"

Invocation of all the REST endpoints should be qualified with the appropriate Bearer token/authz token received from the reference cloud along with other mandatory headers as specified in the respective API documentation.

To proxy a request to a specific device, you will also need the device id of the hardware. Once the device has been claimed, you may fetch all the device id you are currently the owner of by calling the following API:

curl GET 'https://cloud-gateway.<domain-name>/api/owned'  -H 'Authorization: Bearer <id-token>'

You may also get the device id by inspecting the device file system at:

/var/persist/serial

Curl sample, to access VST settings via cloud:

curl GET 'https://cloud-proxy.<domain-name>/proxy/vst/api/vst/settings' -H 'x-device-id: <device-id>' -H 'Authorization: Bearer <authz-jwt-token>'

Device claim via cloud

Following are the APIs to claim/release the ownership of a device by the end-user.

Claim Device

POST  /api/claim-device

Fields in Parameter:
claim_code -  Valid claim code for the device

Fields in Header:
claim_code -  Claim code provided by admin
Authorization - Bearer token

Sample request:

`curl -vvv -X GET --location 'cloud-gateway.<domain-name>/api/claim-device?claim_code=<claim_code>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <id token>'

Release Device

POST /api/release-device

Fields in Header:
x-device-id -  Device id that a user attempts to release ownership of
Authorization - Bearer token

Sample request:

`curl --location 'cloud-gateway.<domain-name>/api/release-device' \
--header 'x-device-id: <device-id>' \
--header 'Authorization: Bearer <id-token>'

Other Cloud APIs

Get User by Access Token

GET /api/user
Return - User profile from  cloud DB

Fields in header:
Authorization - Bearer token

Get User device access

GET /api/owned
Return - List of device ids owned by a user

Fields in header
Authorization - Bearer token