API Key Permissions and Lifetime
An API key gives an application an independent way to authenticate to Files.com. Its account, permission scope, Workspace, path restriction, and lifetime together determine the authority you are giving that application. Choose those controls for the integration's actual work rather than copying the access of the administrator setting it up.
User Keys and Site-Wide Keys
A user key acts with its associated user's permissions, narrowed by the key's own restrictions. It stops working when that user is disabled or deleted. A dedicated non-administrator user is a useful owner when an integration needs a defined set of files and should not inherit a person's unrelated access.
A site-wide key belongs to the site and has no associated user. With Full Access, it has administrative authority within its Workspace scope, including permission to delete files or users. Disabling the administrator who created it does not revoke it, and its actions have no associated username in logs or notifications. Use a descriptive name and a separate key for each integration so its purpose and retirement are clear.
On the Developer API creation form, leaving the User blank and retaining Full Access creates a site-wide administrative key. The API uses equivalent defaults for a Site Administrator's request that omits user_id and permission_set. Select the intended user and permission scope explicitly. API key creation covers those choices.
Permission, Workspace, and Path Scope
| Control | What it limits |
|---|---|
| Associated user | The account's existing permissions and administrative roles. A user key does not add permissions to the account. |
| Files Only | Removes administrative capabilities while retaining permitted file and folder operations. It cannot administer sites, Workspaces, folders, groups, Partners, or billing. |
| Full Access | Preserves management operations available to the key's account and scope. It is different from a user's Full folder permission. |
| Workspace | The Workspace in which the key was created. Creating a key while working in a custom Workspace scopes it there. |
| Path | Direct file and folder requests within one folder and its subfolders. It does not confine the effects of management operations on a Full Access key. |
API keys belong to one site. Parent-site keys do not authenticate to Child Sites, and a user key must belong to a user from the same site where the key was created. Choose the site and Workspace before creating the credential.
A path-restricted file request must keep every accessed path inside the restriction, including both ends of a copy or move. A refused request returns not-authorized/api-key-is-path-restricted, even when the associated user can reach that location through a different credential. The restriction does not change that user's other keys or sessions.
Full Access and Automations
Full Access preserves the management capabilities available to the key. Adding a path restriction does not remove permission to create or manage Automations when the key otherwise has that permission.
An Automation runs with its own permissions, not the path restriction of the API key used to configure it. An integration whose Full Access key can manage Automations can therefore arrange file operations outside the key's restricted path, even though direct file requests to those locations are refused. The Automation must still have permission to access the files it uses. Automation Permissions and Ownership and Permissions (v2) explain which permissions apply to a workflow.
This separation is intentional. The path restriction narrows direct file access, while Full Access keeps management functions available. Do not rely on a path restriction to contain the effects of a Full Access key.
Choosing Access for a Folder-Limited Integration
Use a Files Only key with its path set to the folder the integration needs. Files Only removes administrative capabilities, including managing Automations, so the integration cannot use those capabilities to arrange file operations elsewhere. The path restriction then limits its direct file and folder requests, including both the source and destination of a copy or move.
Whenever possible, associate the key with a dedicated non-administrator user whose folder permissions cover only the required work. Choose the appropriate Workspace as well. These controls limit the authority available to the integration independently of the key's path setting.
If an integration needs Full Access to manage workflows or other settings, evaluate the user permissions and Workspace scope that give it that access. A path restriction alone does not make that key suitable for an integration that must stay within one folder. API Keys covers configuration and the response to a refused file request.
Lifetime, Replacement, and Revocation
API keys authenticate independently of browser sign-in and password-based 2FA. Changing a Files.com password or ending a web session does not revoke an independent API key. Set an expiration date when the integration has a defined end, and use Key Lifecycle Rules when your policy calls for disabling unused keys.
A key's secret is shown only at creation. Store it in the integration's credential storage and keep it out of source files, shared messages, and logs. If the value is lost or needs replacement, create a new key with the required scope, update and verify the integration, then delete the old key. Creating a replacement does not revoke the previous key automatically.
Deleting a key ends that credential's use and associated sessions. It does not undo file operations already completed or remove resources created with it. If the integration created Automations or Share Links, review those resources separately when retiring it. Credentials and Access Revocation explains the distinction between stopping authentication and ending the work or access previously arranged.
Dedicated Desktop and Mobile app credentials are user credentials with an app-session lifetime; they are not the user-created integration keys governed by Allow Users To Create API Keys. S3-compatible credentials are also user-specific. Use the credential type intended for the connection and apply its own lifecycle controls.