API Keys

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.

Creation Controls and Existing Keys

The site-wide Allow Users To Create API Keys setting governs creation of users' own integration keys. It is disabled by default, leaving Site Administrators responsible for creating those credentials. Enabling it lets users create their own keys within their existing account permissions. This lets an organization choose whether integration credentials are issued centrally or by individual users.

The setting governs creation only. Turning it off does not revoke existing keys or remove permission to list, manage, or delete keys that a user is otherwise authorized to manage. Ownership, administrative authority, and the user's account-management permissions still apply. The setting never gives an ordinary user authority over another user's keys.

Use key deletion, expiration, or the appropriate account controls when the intended result is to end existing access. A creation policy cannot replace the lifetime and revocation controls for credentials already issued.

Desktop and Mobile app sign-in issues dedicated app credentials independently of this setting. Those credentials support the app's session and follow its session lifetime. Their existence does not mean that the user has permission to create integration keys.

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

Files Only permits only those file operations and supporting lookups. Every other operation is refused, including reads of site or security configuration. The associated user's administrative access does not expand this scope.

The GPG Encrypt and GPG Decrypt actions use the associated user's GPG key access, which for a Site Administrator includes every key in the current Workspace. A Files Only key cannot run either action, regardless of who owns it. GPG encryption and decryption configured as folder settings still apply to files uploaded with the key.

For Full Access keys created in the Default Workspace, a user key follows its user's current Workspace access; a site-wide key can access every Workspace on the site. Create a key in a Custom Workspace when the integration must stay there. Workspace Scoping gives the full comparison.

API keys belong to one site. A key issued on the Parent Site does not authenticate to a Child Site. Full Access and Files Only user keys require the user to belong to the site where the key was created. Choose the site and Workspace before creating an integration credential.

Desktop and Mobile App sign-in can issue a dedicated key on a Child Site for a Parent Site user who has access to it. That key acts with the user's permissions on that Child Site only. Child Site Administrators cannot create API keys for Parent Site users. API Keys with Child Sites explains the distinction between integration credentials and app sign-in.

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.

A path-restricted key can read the status of only the file migrations it started, such as background copies and moves. This applies to both Files Only and Full Access keys.

Path matching follows Files.com's comparison rules on native storage and Remote Server Mounts. On a remote system that stores reports and REPORTS separately under the same parent, restricting a key to either folder includes both and their contents. Case, accent, and other Unicode differences that compare equally cannot separate access; choose names that compare differently when only one remote folder should be included.

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. Automations v1 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. Access Revocation explains the distinction between stopping authentication and ending the work or access previously arranged.

S3-compatible credentials are also user-specific. Use the credential type intended for the connection and apply its own lifecycle controls.