Authentication

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

Authentication Method	Source	Roles	Purpose
CloudAPI Token	Utility	Owner	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, Ioto offers Login Access Tokens which are granted when a user logs into the Ioto 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, Ioto offers CloudAPI 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.

CloudAPI Tokens

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

CloudAPI 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 CloudAPI 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 CloudAPI Token, you need to obtain a CloudAPI token from the Builder. The CloudAPI token grants administrator privilege via the "owner" role to the caller when accessing Ioto device cloud APIs.

Tokens can be accessed and managed from the Builder Token list or from the Cloud/Edit panel.

HTTP Request Paths

When using CloudAPI 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 CloudAPI token:

curl

curl -X POST https://xrp7t2deqh.execute-api.ap-southeast-1.amazonaws.com/tok/generic/find \
     -H 'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
     -H 'Content-Type: application/json' \
     -d '{"deviceId": "ZXXXXXXXXX", "_type": "Store"}'

url

url https://xrp7t2deqh.execute-api.ap-southeast-1.amazonaws.com/tok/generic/find \
    'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
    '{deviceId: "ZXXXXXXXXX", _type: "Store"}'

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 Ioto service with a user email address and password and utilizing the AccessToken provided in the response with subsequent Ioto API calls.

The Login request is a single HTTP POST request to the Ioto 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.

The request endpoint will vary depending on the AWS region used by the device cloud.

Endpoint

POST https://cognito-idp.${REGION}.amazonaws.com/${USER_POOL_ID}

You can obtain the login Endpoint, ClientId and UserPoolId for the device cloud from the Builder's Cloud / Edit panel under API Access.

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" : "5xxxxxxxxxxxxxxxxxxxxxxxxx"
}

The ClientId and UserPoolId can be obtained from the Builder's Cloud / Edit panel under API Access.

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.
owner	Ability to close the device app account and delete all users and resources.

The Builder will utilize an owner role for the CloudAPI 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.REGION.amazonaws.com/

The REGION can obtain the endpoint from the Builder's Cloud / Edit panel under API Access.

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

The ClientId can obtain the endpoint from the Builder's Cloud / Edit panel under API Access.

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.