Authentication

In order to get access to the API a user or a client application must authenticate with EC. The authentication API creates an access token (which is a JWT token) that has to be set in the Authorization header of the HTTP request of all the subsequent API invocations.

Authentication is itself an API available at the following mount points:

POST /authentication/user
{
  "username": "string",
  "password": "string"
}

or

POST /authentication/apikey
{
  "apiKey": "string"
}

The specific mount point depends on the credential type configured for the user, the developer has to chose the one that fits his needs. See section Users and Credentials for more details.
If successful, the authentication response contains a tokenId field whose value is the access token. The tokenId value has then to be set in the Authorization header of the subsequent HTTP requests. The response contains other useful information as well:

• The scopeId to which the user belongs to
• The userId of the user just authenticated
• The token and its expiration time
• The refresh token and its expiration time

The full response is reported below in JSON format.

{
    "type": "accessToken",
    "id": "ZUYUUdRQB8w",
    "scopeId": "QNvLTfKO1hy",
    "createdOn": "2019-01-01T00:00:00.000Z",
    "createdBy": "LTcVBfHB2lo",
    "modifiedOn": "2019-01-01T00:00:00.000Z",
    "modifiedBy": "LTcVBfHB2lo",
    "optlock": 1,
    "tokenId": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL3d3dy5lY2xpcHNlLm9yZy9rYXB1YSIsImlhdCI6MTU2Njk5NTY0NywiZXhwIjoxNTY2OTk3NDQ3LCJzdWIiOiJBUSIsInNJZCI6IkFRIn0.DDVhcHAmj_KoGKLDyI17P3sRfk8xacGbAJj35kblRuKrthisjL5zPVCXDaqX4Lq9AZJMvEZjNzfFN6TSnaqd4Nk_XvD5a-y5MMm7TEEmupyn1V7oXS9GfMS8snsKRTesb0hY3QC6eHXRpu98zu7wJWNKVIEniZkEhHSXJvFSv17N_YpFu2EFl6aV5AxlpnTcl1O5yVrZvsmIoTiASJCggdVGwugUhxosoH6JMTrqWK0uF0CHatVFFVWRjcOacK_H_kOV67k7H-CkfSlpdFfIn_i3zSCN8MhxA_irAqDYLtAFpkCaxwcB1otEtPXkfHqfHgWcHW6ib7Q4MjPPzvISAQ",
    "userId": "LTcVBfHB2lo",
    "expiresOn": "2019-01-01T00:30:00.000Z",
    "refreshToken": "533a79e1-10e6-42c7-8fec-d3ce0c7535c0",
    "refreshExpiresOn": "2019-01-01T06:00:00.000Z"
}

Resource Identifiers

Resources that map to database entities are identified by unique IDs which are encoded as URL friendly strings. A resource may contain references to other entities.

In the response JSON above the following are resource IDs:

• id
• scopeId
• userId
• createdBy
• modifiedBy

Logging out

When an authenticated user or client application needs to logout it has to invoke the following API:

POST /authentication/logout

API URLs and Scope-Id

Everyware Cloud is a multi tenant application. Tenants (or accounts) are organized hierarchically. The account provides the scope of a tenant by partitioning the devices, the data, the users and other information in the platform as documented in the section Accounts.
The scopeId is the key (in a relational meaning) that identifies a tenant. In EC almost every operation is scoped to a tenant. That's why the scopeId is part of the path in almost every API URL.

For example, the following will retrieve the details of a device:

GET {scopeId}/devices/{deviceId}

The scopeId should be replaced by the value of the same field that is in the response of the authentication request.
For example, if a client application wants to retrieve the details of a device:

• Suppose that Test-User belongs to the account Test-Account.
• Suppose that within Test-Account there is a device registered with clientId=testdev-001 and identified by deviceId=TSlSMdJO1sx
• Suppose the scopeId of Test-Account (as returned in the response to the authentication call) is QNvLTfKO1hy

The details of the device can be retrieved by the following call:

GET QNvLTfKO1hy/devices/TSlSMdJO1sx

Fortunately, most of the times you don't need to specify the actual scopeId in the path since there is a convention that simplifies the most common use cases. The following, in fact, is equivalent to the invocation above:

GET _/devices/TSlSMdJO1sx

The "_" character is a convention for indicating the scopeId of the user currently authenticated with the token.

API Invocation on Child Tenants

A tenant (or account) can optionally have sub tenants (or child accounts). A client application that is authenticated with an account can invoke an API on a child account using the same authentication token by specifying the scopeId of the child account as part of the path of the API URL. To access resources in a child account, its scopeId is needed.

The list of the child accounts and their IDs is retrieved by executing the following API:

GET {scopeId}/accounts

or 

GET _/accounts

For example, a client application wants to retrieve the details of a device that is registered in one of its child accounts. Suppose that:

• Test-Account has a child account named Test-Child-Account which is identified by "id=NM3USkXO1rt*
• Within Test-Child-Account there is a device registered with clientId=testdev-002 and identified by deviceId=GH2MSxZO4tl
• Test-User is the currently authenticated user (the user associated with the access token).

The following will fail because the device does not exist in Test-Account:

GET _/devices/GH2MSxZO4tl

while the following will succeed and the device details will be returned in the response:

GET NM3USkXO1rt/devices/GH2MSxZO4tl

Authorization

When an API is invoked the platform executes an authorization check. As documented in the Permissions section, permissions are attached to user identities so an invocation will fail if the user on whose behalf the invocation is made does not have the required grants.

Refresh the Access Token

In order to increase security, an access token has an expiration time that is returned in the authentication response (field expiresOn). After the expiration time, the access token is no longer valid and any further invocation submitted with that token will fail. By default an access token is valid for 30 minutes after its creation.
However, a client application that holds a valid access token may want to extend its interaction with EC beyond the default 30 minutes without having to execute a new full authentication. In fact, if a full authentication is needed, it is likely the case that the client application should have stored the credentials somewhere to resubmit them later. Unfortunately storing the credentials is often a poor security practice.

In EC an access token that is going to expire or that is already expired can be renewed using the refresh token. The refresh token is contained in the response returned by the authentication request (field refreshToken).

An access token can be refreshed by invoking the following API:

POST /authentication/refresh
{
  "tokenId": "string",
  "refreshToken": "string"
}

The current access token and refresh tokens have to be provided in the body of the request. If the invocation is successful, the response will return new access and refresh tokens with new expiration times while the old tokens are invalidated.
Please consider that the refresh token has an expiration time as well (field refreshExpiresOn). By default the expiration time of the refresh token is 6 hours. After the refresh token has expired, a full authentication is required in any case.

Reference Documentation

EC comes with a detailed reference documentation of each available API. APIs are described using OpenAPI specification and documentation is visualized using Swagger UI, so a simple web browser is needed. The endpoint of the documentation is related to a specific EC instance. Please refer to your EC account administrator in order to get access to your API documentation.