Overview

As part of ongoing improvements, we are updating the way API keys are managed in the system. This change will see the provision of an API key to every user discontinued, with future keys being generated on demand using the new mechanism described below. As part of this change, the way in which the keys are provided to the API as a token header will change to use the Bearer Authentication method.  

Who will this affect?

This change will affect all API users as any existing API key in use will be retired based on the timeline specified below, with the expectation for all users to transition to the new keys by that time.

Details

A new mechanism for API keys has been added and alongside it, a new series of endpoints. The current API key mechanism, where all users have an API key created alongside them is obsoleted and will be removed as part of Phase 2. 

Ignoring the current mechanism, new users will not have API keys created by default, but instead, will be able to create them on demand up to a maximum of 100 keys per user per customer. The new API keys will also come with a label field (to provide some description), an enabled flag (if false the API key will not be valid for usage), and an optional expireAt datetime (if an API key is expired it cannot be edited nor used to authenticate, it can only be deleted).

An API key value (or token) will never be shown after the creation of the API key, so if an issued API is lost or forgotten then the user will need to generate a new one. The database only contains a one way hashed version of the key, just like for passwords, so it is not possible for anyone to impersonate the user using the key even if they have direct access to database. 

The new endpoints are as follows:

GET api/api-key/{id} - Allows the caller to get the information of an API key by its ID

GET api/api-key - Allows the caller to list API keys by user and customer. Optionally it accepts a filter for the "label" field

PUT api/api-key/{id} - Allows the caller to edit an API key to change the label, enabled flag and expiration

POST api/api-key - Allows the caller to create an API key, this is the only endpoint that will return the actual value of an API key

DELETE api/api-key/{id} - Allows the caller to delete an API key

Important: The way you pass the API key is changing!

The new API keys will need to be passed according to the OAuth 2.0 Bearer token format (RFC 6750). That is a request header named "Authorization" will need to be included, which would look like this:

Authorization: Bearer APIKEYVALUEHERE

This change means that the API keys provided by the old and new mechanisms are not interchangeable and old keys will not be accepted via the Authorization header and new keys will need to be generated.  

FAQ

Will API keys work across Alloy regions/environments?

No, each key is specific to a user and customer project. Customers with Live and Staging environments should consider these separately as there is no link between projects across environments. 

Is there a default expiration date for each API key?

No, by default each API key will have no expiration date set and it will be the responsibility of the user to set this on creation or edit.

Will I be able to retrieve my API key at a later date following creation?

In line with best practice, the API key will only be given in the response model on creation. It will then be the creator's responsibility to safely store this key for later use. Only the associated data for the API keys (such as the label, enabled flag and expiration date) will be provided in the GET, PUT and DELETE responses.

Will I need an API key to generate an API key?

Once you've authenticated using your login credentials via the session endpoint and created a customer session, you'll be able to use the customer session token to generate and manage keys using the endpoints described above. So no, you won't be stuck in a infinite loop trying to get an API key 😜. 

Expected Release Date

13th January 2022

Phase 2: Retirement of Existing Token Method

26th January 2023

Overview

We have added a new string property to Workflows, Workflow Actions, and Workflow Action Groups. This property is intended to allow a textual description of the element to be added, to aid others in understanding the use of the element. The description is then returned by any endpoint returning the respective details.

Who will this affect?

This change will affect users who create, edit or read Workflows, Workflow Actions or Workflow Action Groups directly from the API.

Details

The following endpoints have had the property added to their respective request models:

POST api/workflow
PUT api/workflow/{code}
POST api/workflow/{code}/action
PUT api/workflow/{code}/action/{id}
PUT api/workflow-action-group/{code}
POST api/workflow-action-group
POST api/workflow-action-group/{code}/action
PUT api/workflow-action-group/{code}/action/{id}

The following response models also had a description property added to them: 

WorkflowActionWebModel 
WorkflowWebModel
WorkflowActionGroupWebModel 

In all of these instances, the description property is an optional string property with a maximum allowable length of 1024 characters.

Expected Release Date

9th December 2021

Overview

In order to support setting the page orientation of Custom Reports Flow documents, we have added a new property to the CustomReportDocumentDefinitionFlowWebModel called orientation. The property has also been added to endpoints which create or edit the Flow documents definition.

Who will this affect?

This change affects users who are creating and editing custom report flow documents through the API.

Details

Responses that use the CustomReportDocumentDefinitionFlowWebModel will now need to include a definition for orientation. 

Requests to the following endpoints will now require a value for orientation:

POST api/custom-report/{customReportCode}/document-definition 
PUT api/custom-report/{customReportCode}/document-definition/{id}

The orientation property can be one of two options:

• Portrait
• Landscape

For example, creating a Flow document via POST /api/custom-report/{customReportCode}/document-definition

{
  "name": "ExampleDocument",
  "documentDefinitionInfo": {
    "discriminator":
        "CustomReportDocumentDefinitionFlowWebModel",
    "orientation": "Portrait",
    "controls": [...],
    "visualizations": [...]
  }
  "signature": "..."
}

Expected Release Date

9th December 2021

Note

Due to a technical error, this post is being announced after the changes were issued. 

Overview

We have added a Context property to Alloy items and it will now be visible as part of all calls that get or list items.

Users will not be able to edit or delete system items, those with Core and Module context property.

This is to avoid any issues where items that Alloy expects to be present, are unexpectedly removed.

Who will this Affect?

This change will affect users who access items via the API or manage integrations.

Details

Example of GET /api/item/{id} for working days Core item

{
  "item": {
    "itemId": "5c800cc32d14711a9cc642f4",
    "designCode": "designs_workingDays",
    "collection": "Live",
    ...
    "context": "Core",
    "attributes": [...]
  }
}

There has been no change in terms of item creation and users cannot pass an item context on items create or edit. All user-created items will automatically have context set to Customer. 

For example, creating holidays item via POST /api/item

{
  "designCode": "designs_holidays",
  "collection": "Live", 
  "attributes": [
    {
      "attributeCode": "attributes_holidaysName",
      "value": "May holiday"
    },
    {
      "attributeCode": "attributes_holidaysStartDate",
      "value": "2021-05-03"
    }
  ],
  "locked": false
}

Will return response that includes "context": "Customer"

{
  "item": {
    "itemId": "607d5420959e583ad874fc58",
    "designCode": "designs_holidays",
    "collection": "Live",
    ...
    "locked": false,
    "context": "Customer",
    "attributes": [...],
    "signature": "607d5421959e583ad874fc5d"
  }
}

System items delete and edit is forbidden

When trying to delete or edit system items, the API will now respond with a 403Forbidden response, e.g. for working days standard item 5c800cc32d14711a9cc642f4 as above swagger responses are as follows.

Expected Release Date

3rd September 2021

Note

Due to a technical error, this post is being announced after the changes in Phase 1 were issued. 

Overview

When first designing Alloy, we anticipated the need for an item setting that would allow versioning. With this setting enabled, each change to the item would create a new version of the item with only the most recent item being visible in the application. While we still believe this function may hold value in the future, maintaining the feature in the application offers very little benefit over the item audit logs. Instead, the item versions consume storage space unnecessarily when enabled on designs. 

We have therefore taken the decision to remove item versioning for the time being. 

Who will this affect?

The change to remove item versioning will not impact the functionality within the system and is being made to improve performance for customers with large numbers of items. 

This work will mark the properties and endpoints marked as Obsolete to be removed at a later date. If this can cause a problem for API users, we urge you to take action during the time provided before removal as any integrations relying on obsolete properties may cease to function.  

Phase 1

Details

Both DesignWebModel and DesignInterfaceWebModel will not have the versioned property being returned anymore. It was already advertised as optional in the response and it is thus not meant to cause any problem.

The start and end properties ofItemWebModel and ReconstructedItemWebModel are now obsolete and will always return respectively 0000-01-01T00:00:00Z and 9999-12-31T12:59:59Z.

The DesignEditWebRequestModel and DesignCreateWebRequestModel will not accept the versioned property anymore. If the property is passed, it will be ignored.

The ReconstructedItemDeltaWebModel optional properties start and end will not be returned anymore.

The GET api/item-version/{itemId} and the GET api/item-version/item/{id} are now obsolete and will be removed as part of phase 2.

Phase 2

The start and end properties of ItemWebModeland ReconstructedItemWebModel  that were obsoleted during phase 1 will be removed.

The GET api/item-version/{itemId} and the GET api/item-version/item/{id} that were obsoleted during phase 1 will be removed.

Phase 1 Expected Release Date

3rd September 2021

Phase 2 Expected Release Date

March 2022

Overview

We are making a change to the password policy to ensure at least one special character is present when setting an Alloy password. This will increase password complexity in order to prevent unauthorised access to your Alloy account.

Who will this affect?

Current passwords will remain valid even if they do not contain a special character, so this won't impact existing users immediately after release.

However, this will apply to existing users when they change or reset their passwords. The change will also affect new users setting up an Alloy account for the first time.

Details

New user passwords, and existing users changing or resetting passwords, will need to include at least one special character. A special character is a character that is not an alphabetic or numeric character, e.g. @&*[].

Expected Release Date

28th October 2021

Overview

We are making changes to some of our endpoints in order to become fully OpenAPI 3.0 compliant. Additionally, we will be adding Redoc under the /docs path to provide an even easier way of navigating our API definition and explore models that use discriminators.

Who will this affect?

There are several changes to various endpoints as detailed below. None of these changes are expected to be a breaking change and the current method of calling these endpoints will remain compatible.

There will however be a Phase 2 of this work in which we will remove any obsolete endpoints and properties. API users should complete any transition to the new endpoints before the Phase 2 date to avoid issues.

Details

Delete Endpoints

The following endpoints will change to have a query parameter named signature to pass the signature. Passing the signature in the body will be obsoleted and removed in Phase 2:

DELETE api/access-policy/{code}/rule/{id}
DELETE api/custom-report/{customReportCode}/data-source/{code}
DELETE api/custom-report/{customReportCode}/document-definition/{id}
DELETE api/design/{code}/attribute/{attributeCode}
DELETE api/design/{code}/interface/{interfaceCode}
DELETE api/workflow-action-group/{code}/action/{id}
DELETE api/workflow/{code}/action/{id}

User Group Endpoints

There are 2 new user group endpoints to add and remove users from a user group:

POST api/user-group/user/add
POST api/user-group/user/remove

The following two (current) endpoints will be marked obsolete and removed in Phase 2; note, these will no longer be visible through the swagger documentation.

POST api/user-group/user
DELETE api/user-group/user

Role User Endpoints

There are 2 new role endpoints to add and remove users from a role:

POST api/role/user/add
POST api/role/user/remove

The following two (current) endpoints will be marked obsolete and removed in Phase 2; note, these will no longer be visible through the swagger documentation. 

POST api/role/user
DELETE api/role/user

Role Group Endpoints

There are 2 new role endpoints to add and remove groups from a role:

POST api/role/group/add
POST api/role/group/remove

The following two (current) endpoints will be marked obsolete and removed in Phase 2; note, these will no longer be visible through the swagger documentation. 

POST api/role/group
DELETE api/role/group

Expected Release Dates

Phase 1 : 29th September 2021

Phase 2 : 31st March 2022

Overview 

As part of our ongoing work to provide more detailed messaging from our API, we will be updating our responses to contain information regarding how close the caller is to reaching this limit in response headers.

Who will this affect?

This change will only affect users that are likely to exceed the API rate limit by providing them with greater feedback when this may occur. 

Details

As described in a previous post, our API will limit the number of calls that a user can make in line with our rate limiting policy.

We will be updating our responses to contain information regarding how close the API caller is to reaching this limit in response headers, for example:

X-Rate-Limit-Remaining: 99
X-Rate-Limit-Reset: 2021-03-16T11:08:08.0232125Z

This message informs you that if you make more than another 99 requests before the specified time, you will be subject to rate-limiting.  When the limit is exceeded, requests will then fail with HTTP 429, and there will be a response header letting you know how many seconds to wait until you will again be able to make requests, for example:

Retry-After: 15

Note that these are the standard headers recognised for HTTP rate limiting.

Expected Release Date

July 29th 2021

Overview

AQS expressions now support the ability to run queries with conditions on an item level count.

Who will be affected?

All existing users will be able to take advantage of this feature through the newly added AQS Count node.

Details

An item level count allows to have a condition on the number of items connected through a link attribute being equal, greater than, etc. to the value of another attribute on the same item.

Example Use Case

As an example, we can consider a query that wants to fetch the title and subtitle of all projects that are over capacity. That is all projects that have a number of tasks greater than or equal to their capacity, contained in attribute attributes_projectsCapacity_60464441c14e5d000ad7e47.

{
  "type": "Query",
  "properties": {
    "attributes": [
      "attributes_itemsTitle",
      "attributes_itemsSubtitle"
    ],
    "collectionCode": [
      "Live"
    ],
    "dodiCode": "designs_projects"
  },
  "children": [
    {
      "type": "GreaterThan",
      "properties": {
        "inclusive": true
      },
      "children": [
        {
          "type": "Count",
          "properties": {
            "groupBy": "attributes_projectsTasks"
          }
        },
        {
          "type": "Attribute",
          "properties": {
            "attributeCode": "attributes_projectsCapacity_60464441c14e5d000ad7e479"
          }
        }
      ]
    }
  ]
}

Prior to this change, users could only compare a count node against a static Number node.

Expected Release Date

June 24th 2021

Overview

In order to improve the accessibility of Alloy Meshes, we will be adding support for Open API JSON and endpoint documentation. Following a detailed review of the exposed endpoints and data models, we will also be acting to implement the following deprecations to provide better consistency between naming and conventions with the Alloy Core, Extended and Forge API's. Finally, we will be making changes to the way in which the security token is passed to the Meshes to improve security. 

Security token to be removed from query string

We will no longer be accepting the token parameter which represents an Alloy API token on the query string, this should be passed via the HTTP headers in all future requests using the same key of token.

Example CURL before:

curl -X 'POST' \
  'http://localhost:3000/aws-iot/update-device?itemId=abc?token=123' \
  -H 'accept: application/json' \

Example CURL after:

curl -X 'POST' \
  'http://localhost:3000/aws-iot/update-device?itemId=abc' \
  -H 'accept: application/json' \
  -H 'token: 123' \

MeshResponseWithItemWebModel renames property itemResponse to item

The following meshes are expected to return a response which includes an item payload under the property itemResponse.

• alloy-push-mayrise-notice-mesh
• json-push-alloy-mesh
• telensa-fault-push-alloy-mesh

This property is being renamed to item but we will continue to return itemResponse until the date specified below for Phase 2. 

Example response before:

{
  "itemResponse": {
    "itemId": "af32ef...",
    ...
  }
}

Example response after:

{
  "itemResponse": {
    "itemId": "af32ef...",
    ...
  },
  // we will duplicate the data in the recommended item property
  "item": {
    "itemId": "af32ef...",
    ...
  },
}

Risk calculation mesh to remove itemsResponse property

The risk calculation mesh alloy-push-risk-calculation-mesh is removing the itemsResponse property as it was not correctly indicating the success of the response model, it isn't required and will therefore be removed as part of Phase 1 changes. 

When do these changes take effect?

The above changes will be rolled out in June 2021, with deprecations finally removed in January 2022 with the following expected release dates: 

Expected Release Date

Phase 1: June 24th 2021

Phase 2: February 24th 2022