files-com/files-cli/filescom-api-keys

filescom-api-keys

An APIKey is a key that allows programmatic access to your Site.

API keys use the owning user's permissions, narrowed by the key's permission set, workspace scope, and any folder path restriction. If an API key is created without a user owner, it is considered a site-wide API key. Site-wide API keys with the files_only permission set are restricted to file-user permissions and workspace scoping.

Set path when creating a files_only key to confine it to that folder and its descendants. Only files_only keys can be created with a path, apart from office_integration keys, which require one. Except for office_integration keys, the path does not need to exist when the key is created. The restriction applies to the files, folders, and file_actions endpoints, on every path those requests access, including both source and destination paths for copy and move operations. Requests to those endpoints outside the restriction are denied with not-authorized/api-key-is-path-restricted. It never grants additional access to the owning user. A key with the files_only permission set can use only those endpoints, excluding the GPG Encrypt and GPG Decrypt file actions, plus GET /file_migrations/{id} to follow file operations under the visibility rules below and GET /api_key to read its own record. Because the path restriction covers exactly the endpoints a files_only key can use, the two together keep a key inside one folder, while a path on any other permission set would leave the key's other endpoints unrestricted. Both GPG file actions and every other endpoint deny a files_only key with not-authorized/api-key-only-for-file-operations. Folder-configured GPG encryption and decryption still apply to files uploaded with a files_only key.

On GET /file_migrations/{id}, any key with a path can read only migrations it started. Without a path, user-owned keys retain their user-scoped access, including Desktop and Mobile keys in the owning user's Workspace. A site-wide key bound to a Workspace can read a migration only when its source and destination are both in that Workspace. Workspace binding applies to every files_only key, including Workspace 0, and to full-access keys in a named Workspace. A full-access site-wide key in the default Workspace can read migrations across the Site. Migrations outside the caller's visibility return not-found.

We recommend registering API keys to service users wherever possible and then using User or Group Permissions to restrict that API Key appropriately.

All subcommands also accept the flags documented in `CONTEXT.md` (--api-key, --format, --workspace-id, --debug, and the pagination flags --cursor / --per-page / --max-pages on list). Those are not repeated below.

Commands

files-cli api-keys list

List API Keys.

files-cli api-keys find-current

Show information about current API key. (Requires current API connection to be using an API key.).

No flags beyond the global ones.

files-cli api-keys find

Show API Key.

files-cli api-keys create [path]

Create API Key.

files-cli api-keys update-current

Update current API key. (Requires current API connection to be using an API key.).

files-cli api-keys update

Update API Key.

files-cli api-keys delete-current

Delete current API key. (Requires current API connection to be using an API key.).

No flags beyond the global ones.

files-cli api-keys delete

Delete API Key.