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 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 roles or 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. A path restriction limits direct file operations made with the key, but does not limit its administrative capabilities.

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 disable one key without affecting your other automated processes.

User keys are associated with a single user account. The key's permission scope, path restriction, and Workspace scope can further narrow the access available through that key.

Permission Scopes

When creating or editing an API key, you can set its permission scope to Full Access or Files Only. 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 path restriction limits direct file and folder operations; it does not restrict management operations such as creating Automations.

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.

Files Only keys are built for AI agents and other file-only automation, where the key 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

An API key's path restriction limits direct file and folder operations to one folder and its contents, including subfolders. Use it when an integration needs only part of the file access available to its associated user, such as one folder used to exchange files with another system. The restriction does not change the user's access through other keys or sessions.

Use Files Only together with a path restriction when an integration must be confined to that folder. A path restriction on a Full Access key does not provide that protection: the key can still create Automations or perform other management operations when it otherwise has permission to do so. Those Automations can operate outside the key's restricted path using their own permissions. This is by design. The path restriction controls direct file requests, not the permissions of workflows configured with the key. API Keys explains this distinction when choosing access for an integration.

Set the path field when creating the key through the API. Path restrictions apply to both Full Access and Files Only keys. To create a key for file operations only, also set permission_set to files_only. The restriction works alongside the key's Workspace scope and associated user's permissions. It never grants access the user does not already have.

For direct file and folder requests, every path the 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 directly copy that file to shared/archive or read files there.

A direct file or folder request outside the allowed path is refused. The API returns not-authorized/api-key-is-path-restricted when the key's path restriction denies access, even if the associated user can access that location through another key or session.

Workspace Scoping

An API key is restricted to the Workspace it is created in. A site administrator manages API keys for whichever workspace they are currently working in, so to create a key scoped to a custom workspace, switch to that workspace and create the key there.

Creating Site-Wide API Keys

Only Site Administrators can create site-wide API keys. 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. Adding a path restriction limits direct file operations, but does not remove administrative access or confine workflows created with the key to that path.

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.

The API uses the same defaults for requests made by a Site Administrator. Omitting user_id creates a site-wide key, and omitting permission_set defaults it to full (Full Access). Set user_id to a user's ID to create a user key, or set it to 0 to associate the key with your current user account. Set permission_set to files_only to limit the key to file and folder operations.

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 any user. 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. In the API, provide its user ID or use user_id: 0 for your current user account. 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 API keys automatically at sign-in. These keys serve as long-lived session tokens so users can return to their files without repeatedly signing in. This sign-in process is available even when Allow Users To Create API Keys is disabled; that setting controls credentials users create for their own integrations.

The site's separate Desktop App Session Lifetime and Mobile App Session Lifetime settings control the expiration of each app's tokens independently. These tokens appear in responses to GET /user/api_keys, but the web interface's API key list excludes them. Seeing an app session key in the API therefore does not mean that user-created integration keys are enabled.

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.

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

You can temporarily disable a user API key by updating its permission set to none. You can later reactivate the same key by updating its permissions again.

To permanently revoke a key, delete it. Only Site Administrators can delete site-wide API keys. Any Site Administrator can delete user keys for any user. If your site settings allow it, users who are not Site Administrators can delete their own user API keys. 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 the contents of your key, delete the existing API Key entry and create a new one.

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.

User-specific API keys have an additional rule: the user must belong to the same site where the key was created. A key created on a child site for a user from the parent site does not work. Only users who belong to the same site as the key can use it.