API Keys
An API key is an authentication credential used with the Files.com API and SDKs to integrate Files.com with your own applications, such as iPaaS applications. API keys can also authenticate FTP, SFTP, and WebDAV connections. API keys are independent from one another. Generating a unique API key for each application or server lets you revoke any one of them without disrupting your other integrations.
Types of API Keys
Files.com supports two types of API keys: site-wide keys and user keys. A site-wide key is not associated with a user account. A user key provides access based on the permissions of its associated user. A Full Access user key includes the administrative API functions available to its associated user. It does not give that user additional permissions.
We strongly recommend associating all API keys with a non-administrator user account whenever possible. Site-wide keys with Full Access, or Full Access keys associated with a Site Administrator's user account, can perform any function available in their Workspace scope, including deleting files or users.
Site-wide keys with Full Access have the same administrative access as a Site Administrator within their Workspace scope. We recommend generating a separate site-wide key for each custom integration that requires one, so that you can revoke one key without affecting your other automated processes.
User keys are associated with a single user account. The key's permission scope and Workspace scope can further narrow the access available through that key. A Files Only key can also have a path restriction.
Permission Scopes
Choose Full Access or Files Only when creating an API key. Its permission scope is fixed at creation; neither the key itself nor an administrator can change it afterward. A different scope requires a replacement key.
A Full Access user key permits its associated user's operations within the key's Workspace scope. It does not grant the user any additional permissions, and the Full Access scope of an API key is not the same as the Full Folder Permission of a user.
A Files Only key can only interact with files and folders. It cannot act as a site administrator, workspace administrator, folder administrator, group administrator, or partner administrator, and it cannot access billing.
A Files Only key cannot run ad hoc GPG Encrypt or GPG Decrypt on a file. This applies to user keys regardless of the associated user's administrative permissions, and to site-wide keys. GPG encryption and GPG decryption configured as folder settings still apply to files uploaded with the key.
Files Only keys are built for AI agents and other file-only automation, where the integration needs to move files but must never administer the site. They are also the right key to issue when another Files.com site connects to yours through a Files.com Remote Server, since that connection only ever works with files and folders.
Connecting to Another Files.com Site covers that setup for both sites. We recommend Files Only for any integration that only reads and writes files.
Path Restrictions
Only Files Only integration keys support a path restriction. Files Only limits what the key can do to file and folder operations, and the path limits where it can do that work: one folder and its contents, including subfolders. Use this combination when an integration needs only one exchange folder, even if its associated user has access elsewhere.
Full Access also permits management operations available to the account, such as configuring Automations. Those Automations run with their own permissions and can work in other folders. A single folder restriction would not describe all the work an integration can arrange using the key, so Files.com refuses creation of a Full Access key with a path. An integration that needs Full Access gets its access from its account's permissions and Workspace scope.
A path restriction works alongside the key's Workspace scope and associated user's permissions; it never grants access the user does not already have. It does not change the user's access through other keys or sessions. API key configuration documents programmatic creation and configuration.
Every path a file or folder request accesses must be within the restricted folder. For copy and move operations, both the source and destination must be within it. For example, a key restricted to shared/docs can work with shared/docs/report.pdf when its user has the required permissions, but cannot copy that file to shared/archive or read files there.
A file or folder request outside the allowed path is refused, even if the associated user can access that location through another key or session.
The restricted folder is identified using Files.com's path comparison rules, which ignore case and accents on native storage and Remote Server Mounts alike. If a mount contains separate archive/reports and archive/REPORTS folders, a restriction to archive/reports includes both folders and their contents. It does not include a differently named sibling such as archive/reports-private.
Use names that compare differently when an integration must be restricted to only one of the remote folders.
The remote system can also treat different Files.com paths as one folder, such as HR and HR. on storage that removes trailing periods. A key restricted to their parent can reach that content through either permitted path; a Permission Fence on HR does not cover HR.. Keep confidential content outside the key's permitted mounted subtree. Path Matching on Mounted Storage explains how to separate access when the two systems' naming rules differ.
Workspace Scoping
A key's Workspace and permission scope determine whether an integration stays within one Workspace or can use its account's access across Workspaces.
| Key created in | Key type and permission scope | Workspace access |
|---|---|---|
| Custom Workspace | User or site-wide key, Full Access or Files Only | Only the Workspace where the key was created. |
| Default Workspace | User or site-wide key, Files Only | Only the Default Workspace, even when the associated user has access to other Workspaces. |
| Default Workspace | User key, Full Access | The Default Workspace and Custom Workspaces the associated user can access. |
| Default Workspace | Site-wide key, Full Access | Every Workspace on the site, with the same authority as a Site Administrator. |
Selecting a Workspace for an API request does not expand the key's access. A request selecting a Workspace outside the key's allowed scope is refused.
A Full Access user key created in the Default Workspace uses the user's current permissions in the selected Workspace, including Workspace Administrator access where granted. Access is evaluated on every request, so adding or removing the user's Workspace access changes the access available through an existing key without recreating it.
To create a key confined to a Custom Workspace, switch to that Workspace before creating it. This confines the integration to that Workspace even when its associated user has broader access.
User Key Creation
The site-wide Allow Users To Create API Keys setting controls whether users can create credentials for their own integrations. This lets Site Administrators keep control of integration credentials while users continue working in the Files.com apps. User keys remain subject to the associated user's permissions and the key's access scope.
By default, only Site Administrators can create these integration keys. Enabling the setting lets other users, including Workspace Administrators, create their own.
When the setting is disabled, users who are not Site Administrators cannot create API keys for their own integrations. Site Administrators can create or remove API keys for individual users.
Disabling the setting does not revoke existing keys or prevent users from listing or deleting keys they are otherwise authorized to manage, including keys created for them by an administrator. The user's account-management permissions still apply.
An existing Full Access key can shorten, extend, or remove its own expiration even when user key creation is disabled, including when the key belongs to a Shared/Bot user. These expiration-only updates change an issued credential without creating another one. They do not give the user permission to manage other users' keys or change other key settings.
Desktop and Mobile app credentials can also shorten or extend their own expiration, but remain limited by the app's session lifetime measured from the original sign-in. Files Only keys cannot update their own expiration. API key lifetime controls compares these scopes and explains when expiration needs to be managed separately from the integration.
Whether the setting is enabled or disabled, users who are not Site Administrators, including Workspace Administrators, cannot create, view, edit, or delete API keys for other users, even within a Workspace they administer.
To end an integration's existing access, revoke its key or apply the appropriate account control. API Keys explains how the creation policy differs from key scope, expiration, and revocation.
Creating Site-Wide API Keys
Only Site Administrators can create site-wide API keys, including keys limited to a single Workspace. On the Developer API page, the Create API Key form opens with the User field blank and Full Access selected.
If you enter a name and save without changing those defaults, Files.com creates a site-wide key with Full Access. This is not a key for your own administrator account.
It has administrative access within the key's Workspace scope, including the ability to delete files or users.
To create a key for yourself or another user, select that account in the User field. To prevent a key from performing administrative operations, select Files Only. Whenever possible, use both protections: associate the key with a user who is not a Site Administrator and select Files Only for an integration that only needs to work with files and folders.
A site-wide key belongs to the site, not to the Site Administrator who created it. The key has no associated user, so disabling or deleting the creator's account does not disable the key. It continues working until a Site Administrator deletes it or its expiration date passes. Actions performed with a site-wide key have no associated username in logs or notifications.
A user key has the opposite lifecycle. It stops working when its associated user is disabled or deleted.
Provide a human-readable name so you can track why each key was generated. You can also include an expiration date.
The key value is shown only when the key is first created. You cannot retrieve the value later, so save it immediately.
Creating User API Keys
Site Administrators can create user API keys for users who belong to their site. If your site settings allow it, users who are not Site Administrators can create their own user API keys.
A user API key must be associated with a user. In the web interface, select the account in the User field. Also provide a human-readable name to track why the key was generated. You can include an expiration date.
The key value is shown only when the key is first created. You cannot retrieve the value later, so store it immediately.
The Desktop App and Mobile App also receive dedicated user credentials automatically at sign-in. These serve as long-lived session tokens so users can return to their files without repeatedly signing in. Online Editor integrations use temporary credentials for viewing and editing through the editor service. These credentials remain available when Allow Users To Create API Keys is disabled, so a policy against user-created integrations does not prevent ordinary app and editor work.
The site's separate Desktop App Session Lifetime and Mobile App Session Lifetime settings control the expiration of each app's tokens independently. App connections are managed separately from the web interface's integration-key list. Use the app access and session controls to manage that access.
The app and editor credential reference explains their permitted operations, direct API issuance, and visibility. Requesting one of these credential types does not give the user permission to create a Full Access or Files Only integration key.
S3 Compatible API Keys
You can create S3-compatible API keys by selecting the Enable use with Inbound S3-compatible clients option when creating a key. This enables connections to your Files.com site from S3-compatible applications using the Amazon S3 protocol.
The resulting S3 Access Key ID and Secret Access Key carry the same API key's permission scope, Workspace scope, and path restriction. Select Files Only and set a path restriction when the S3 client needs only one folder and its contents. S3 access control explains how those limits apply to copies and multipart uploads.
S3-compatible API keys are tied to individual user accounts and do not support site-wide access. The S3 connection signs in as the associated user, so choose the account whose file access the integration needs.
That user must have S3-Compatible Endpoint protocol permission. Creating an S3-compatible key does not grant this permission, and the separate Web, Desktop App, and API permission does not control S3 access.
When you enable this option, Files.com displays an Access Key ID and a corresponding Secret Key. Store these values immediately. Once you close the window, you cannot retrieve them again.
Disabling and Revoking API Keys
Delete a key to revoke it, or set an expiration date to end its access at that time. Only Site Administrators can delete site-wide API keys. Any Site Administrator can delete user keys for any user.
Users with permission to manage their own account can delete their own user API keys, including when Allow Users To Create API Keys is disabled. Key Lifecycle Rules can also end a key's access. Changing a password or ending a web session does not revoke API keys.
Viewing Existing API Keys
The key value is shown only when the key is first created. You cannot access the value of an existing API Key afterward. This is a standard security precaution that most platforms take to maintain the secrecy of important credentials.
If you have lost a key's value or need a different permission scope, create a replacement with the permissions and restrictions the integration needs, and save the new value. Update every integration using the old key and verify the required operations with the replacement before deleting the old key. Creating a replacement does not revoke the old key, so existing integrations can continue using it during the changeover.
Using API Keys with Child Sites
An API key is linked to a single site. Whether the key is site-wide or for one user, it only works with the site it was created on. A key created on a Parent Site only works on that Parent Site; a key created on a Child Site only works on that Child Site.
Full Access and Files Only user keys require the user to belong to the same site where the key was created. For a custom integration that connects directly to a Child Site, create its user account and API key on that Child Site.
The Desktop App and Mobile App support Parent Site users without requiring a separate Child Site account. When a Parent Site user signs in to a Child Site they can access through either app, the app automatically receives a dedicated user key issued on that Child Site. The key acts with that user's permissions on that Child Site only; it does not authenticate to the Parent Site or another Child Site.
Child Site Administrators cannot create API keys for Parent Site users.