API Keys for Users and Devices

  • Updated

Introduction

Flywheel provides CLI, SDK, and Connector interfaces for users to accomplish powerful, scriptable, and customizable data and system operations not available in the Web UI. Usage of these interfaces requires authenticating with an API Key to ensure every request is associated with an authorized User or Device.

Warning

Support for Legacy API Keys will end with the 18.0 release of Flywheel Enterprise expected to be released in February 2024. Once upgraded to version 18.0.0 or later, a Flywheel site will reject all authentication attempts that use Legacy API Keys.

Notes: 
  • All users should migrate to using Enhanced API Keys (instructions below) as soon as feasible, to avoid disruption when support ends.
  • Compromised API Keys can be used to impersonate users and devices. If an API Key is inappropriately disclosed, it should be promptly revoked and replaced with a new API Key.
  • Disabling a User account or device interface does not cause API Keys to be revoked, but will cause any use of any corresponding API Keys to be rejected.

User API Keys

User API Keys each belong to one and only one user account. All interactions using the User API Key will be logged as originating from the associated user, and only operations that the user has permission to do will be permitted. A user can manage their User API Keys in their User Profile page.

 

User Profile - API Keys.png

 

User API Keys are commonly used with the Flywheel CLI and SDK.  When a Flywheel user account is disabled, all use of that user’s API Keys is rejected .

 

Device API Keys

Device API Keys each belong to one and only one device interface. Site Admins manage the registration of authorized devices. All interactions using the Device API Key will be logged as originating from the associated Device, and limited to operations only allowed for devices. Site Admins can manage all registered devices and Device API Keys in the Admin Interfaces page.

 

Device Settings - API Keys.png

 

Device API Keys are commonly used with the Flywheel CLI and Connectors for bulk and/or automated data import.

 

Enhanced vs. Legacy

Enhanced API Keys

Enhanced API Keys are the new and only type of User and Device API Keys that may be created with Flywheel Enterprise version 16.19.0 and later. Enhanced API Keys provide improved storage security, require expiration, and support multiple API Keys per user/device.

Upon logging into the Flywheel Enterprise Web UI, a warning will appear for any Enhanced API Keys that are expired, or will expire within 7 days.

 

Login Warning - API Key Expiration.png

 

Legacy API Keys

Legacy API Keys are the type of User and Device API Keys created with Flywheel Enterprise versions prior to 16.19.0. These API Keys are easy to identify in the web UI, can no longer be created.

Support for Legacy API Keys will end with the 18.0 release of Flywheel Enterprise expected to be released in February 2024. Once upgraded to version 18.0.0 or later, a Flywheel site will reject all authentication attempts that use Legacy API Keys.

To migrate away from a Legacy API Key:

  1. Confirm your Flywheel version is 16.19.0 or later
  2. Create a new API Key - Learn more about creating API Keys for Users and Devices.
  3. Update any Flywheel CLI, SDK, or custom applications to use the new API Key 
  4. Delete the Legacy API Key from Flywheel

Resources