---
agentTools:
  projectIndex: https://ec.eurotech.com/llms.txt
---

# Getting Started

# 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:

[block:code]
{
  "codes": [
    {
      "code": "POST /authentication/user\n{\n  \"username\": \"string\",\n  \"password\": \"string\"\n}\n\nor\n\nPOST /authentication/apikey\n{\n  \"apiKey\": \"string\"\n}",
      "language": "text"
    }
  ]
}
[/block]

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](https://ec.eurotech.com/docs/users) 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.

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

# 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:

[block:code]
{
  "codes": [
    {
      "code": "POST /authentication/logout",
      "language": "text"
    }
  ]
}
[/block]

# 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](https://ec.eurotech.com/docs/installation).
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:

[block:code]
{
  "codes": [
    {
      "code": "GET {scopeId}/devices/{deviceId}",
      "language": "text"
    }
  ]
}
[/block]

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:

[block:code]
{
  "codes": [
    {
      "code": "GET QNvLTfKO1hy/devices/TSlSMdJO1sx",
      "language": "text"
    }
  ]
}
[/block]

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:

[block:code]
{
  "codes": [
    {
      "code": "GET _/devices/TSlSMdJO1sx",
      "language": "text"
    }
  ]
}
[/block]

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:

[block:code]
{
  "codes": [
    {
      "code": "GET {scopeId}/accounts\n\nor \n\nGET _/accounts",
      "language": "text"
    }
  ]
}
[/block]

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*:

[block:code]
{
  "codes": [
    {
      "code": "GET _/devices/GH2MSxZO4tl",
      "language": "text"
    }
  ]
}
[/block]

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

[block:code]
{
  "codes": [
    {
      "code": "GET NM3USkXO1rt/devices/GH2MSxZO4tl",
      "language": "text"
    }
  ]
}
[/block]

# Authorization

When an API is invoked the platform executes an authorization check. As documented in the [Permissions](https://ec.eurotech.com/docs/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:

[block:code]
{
  "codes": [
    {
      "code": "POST /authentication/refresh\n{\n  \"tokenId\": \"string\",\n  \"refreshToken\": \"string\"\n}",
      "language": "text"
    }
  ]
}
[/block]

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.