Skip to content

Logo Logo

API Keys for Users and Devices

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.

Instruction Steps

Warning: Support for Legacy API Keys will end with the 19.0 release of Flywheel Enterprise, expected to be released in July 2024.

Once upgraded to version 19.0.0 or later, a Flywheel site will reject all authentication attempts that use Legacy API Keys.

Note:

  • 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 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 can 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, but can no longer be created.

Support for Legacy API Keys will end with the 19.0 release of Flywheel Enterprise, expected to be released in July 2024. Once upgraded to version 19.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 - Follow the steps above to create 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