Authentication

The Builder service provides different authentication methods for two use cases:

Authentication Method	Source	Roles	Purpose
BuilderAPI Token	Utility	Admin	Admin utilities running in the cloud or on-premises
Login Access Token	Browser	User, Admin	A logged in user from a web browser app

For logged in users, Builder offers Login Access Tokens which are granted when a user logs into the Builder service. These tokens grant access according to the user's authorized role. All actions using Login Access tokens are limited in scope by the user's role and to resources owned by the logged in user.

For utility service commands, Builder offers BuilderAPI Tokens that provide full access to the device cloud and the all resources in the cloud. These tokens offer access to all user accounts utilizing the device cloud.

BuilderAPI Tokens

BuilderAPI Tokens are used by utility commands and services for full administrative access to the resources of the device cloud.

BuilderAPI Tokens have flexible lifespans and can be managed to set their lifespan or to suspend, resume, revoke or replace the token. You can have one or more BuilderAPI tokens active at a time. This is useful to deploy a new token and then subsequently revoke the old token.

To authorize requests using a BuilderAPI Token, you need to obtain a BuilderAPI token from the Builder. The BuilderAPI token grants administrator privilege via the "admin" role to the caller when accessing the Builder service.

Tokens can be accessed and managed from the Builder Token list.

HTTP Request Paths

When using BuilderAPI tokens, the request URLs are modified to include a "/tok" URL prefix before the URL path.

Token Authentication Example

Here is an example to issue a request from the command line using curl or the Ioto url command using a BuilderAPI token:

curl

curl -X POST https://api.admin.embedthis.com/api/tok/user/get \
     -H 'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
     -H 'Content-Type: application/json' \
     -d '{"id": "ZXXXXXXXXX"}'

url

url https://api.admin.embedthis.com/api/tok/user/get \
    'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
    '{id: "ZXXXXXXXXX"}'

Note: the url command is a utility command that is installed with the Ioto agent. It can automatically sense the arguments as either headers, or body data. JSON body data can be passed as JSON5 (like JS) and can thus omit quotes on property keys.

Login Access Tokens

A Login Access Token may be obtained by logging into the Builder service with a user email address and password and utilizing the AccessToken provided in the response with subsequent Builder API calls.

The Login request is a single HTTP POST request to the Builder Cognito authentiction endpoint.

Login Request

The login request authenticates the user's credentials and exchanges them for a time-limited access token. The access token will be valid for a period of 60 minutes and can be refreshed using a RefreshToken contained in the response. The RefreshToken is valid for a period of 30 days.

Endpoint

POST https://cognito-idp.us-east-1.amazonaws.com/us-east-1_W9auNFejR

Request Headers

X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
Content-Type: application/x-amz-json-1.1
Origin: myapp.ioto.me

Request Body

{
   "AuthParameters" : {
      "USERNAME" : "yourusername@example.com",
      "PASSWORD" : "yourpassword"
   },
   "AuthFlow" : "USER_PASSWORD_AUTH",
   "ClientId" : "5g3qt5mitfa4q1jlrlibeviedn"
}

Response

If the request is successful, you will receive a payload response that contains an AccessToken, RefreshToken and ExpiresIn duration.

The AccessToken should be used in an Authorization HTTP header with subsequentIoto API calls. The RefreshToken can be used to refresh the access token before it expires. The ExpiresIn property defines how long (in seconds) the access token will be valid before expiring.

{
    "AuthenticationResult":{
        "AccessToken": "...",
        "IdToken": "....",
        "RefreshToken": "....",
        "TokenType": "Bearer",
        "ExpiresIn": 3600
    }
}

Example

The following example uses the Ioto curl utility to issue an authentication request based on the authentication credentials in a ./creds.json file.

curl

curl -X POST \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
  -H 'Content-Type: application/x-amz-json-1.1' \
  --data @creds.json \
  https://cognito-idp.us-east-1.amazonaws.com/

url

$ url https://cognito-idp.us-east-1.amazonaws.com/ \
    'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
    'Content-Type: application/x-amz-json-1.1' \
    @creds.json

Roles

When user accounts are created in the device app, the user is authorized with an access role that determines the scope of access for the user. The following three roles are supported:

Role	Capabilties
user	Ability to view but not modify service depending resources.
admin	Ability to modify all resources and fully administer the account.

The Builder will utilize an admin role for the BuilderAPI authentication token. This gives the ability to manage multiple accounts and devices over all users.

Refreshing Login Tokens

Access tokens expire after 60 minutes. However, you can refresh the access token without requiring the user to re-login by using the RefreshToken that was returned when first logging in. Refresh tokens expire after 30 days.

Endpoint

POST https://cognito-idp.us-east-1.amazonaws.com/us-east-1_W9auNFejR

Request Headers

X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
Content-Type: application/x-amz-json-1.1

Request Body

{
   "AuthParameters" : {
      "REFRESH_TOKEN": "...",
   },
   "AuthFlow" : "REFRESH_TOKEN_AUTH",
   "ClientId" : "5g3qt5mitfa4q1jlrlibeviedn"
}

Response

If the request is successful, you will receive the following payload response. The AccessToken should be used in an Authorization HTTP header with Ioto API calls . The RefreshToken should be used to refresh the access token before it expires. The ExpiresIn property defines how long the token will be valid.

{
    "AuthenticationResult":{
        "AccessToken": "...",
        "IdToken": "....",
        "RefreshToken": "....",
        "TokenType": "Bearer",
        "ExpiresIn": 3600
    }
}

Logout

There is not an explicit sesion logout API. To logout, discard and erase the access and refresh tokens from any local storage and remove any browser session state associated with the tokens.