Skip to content

Authentication

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

Authentication Method Source Roles Description
CloudAPI Token Utility Owner An device builder's admin service 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.

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

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 authentiction endpoint.

Roles

When device manager user accounts are created, each user is authorized with an access role that determines the scope of access for the user. The following two 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 owner role for the CloudAPI authentication token. This gives the ability to manage multiple accounts and devices over all users.

Builder Role Capabilties
owner Ability to close the manager account and delete all users and resources.

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. For example:

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

You can obtain the login endpoint for the device cloud from the Builder's Manager / Edit panel under API Access.

Endpoint 

1
POST https://cognito-idp.REGION.amazonaws.com/

Request Headers

1
2
3
X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
Content-Type: application/x-amz-json-1.1
Origin: mymanager.ioto.me

Request Body

1
2
3
4
5
6
7
8
{
   "AuthParameters" : {
      "USERNAME" : "yourusername@example.com",
      "PASSWORD" : "yourpassword"
   },
   "AuthFlow" : "USER_PASSWORD_AUTH",
   "ClientId" : "5g3qt5mitfa4q1jlrlibeviedn"
}

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

Response

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

The AccessToken should be used in an Authorization HTTP header with Ioto 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.

1
2
3
4
5
6
7
8
9
{
    "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. 

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

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

1
POST https://cognito-idp.REGION.amazonaws.com/

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

Request Headers

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

Request Body

1
2
3
4
5
6
7
{
   "AuthParameters" : {
      "REFRESH_TOKEN": "...",
   },
   "AuthFlow" : "REFRESH_TOKEN_AUTH",
   "ClientId" : "5g3qt5mitfa4q1jlrlibeviedn"
}

The ClientId can obtain the endpoint from the Builder's Manager / 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.

1
2
3
4
5
6
7
8
9
{
    "AuthenticationResult":{
        "AccessToken": "...",
        "IdToken": "....",
        "RefreshToken": "....",
        "TokenType": "Bearer",
        "ExpiresIn": 3600
    }
}

Example

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

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.