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 key for a Site Administrator provides full access to the entire API; a key for a user who is not a Site Administrator provides access only to files that user can access and cannot use site administration functions in the API.

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

User keys are associated with a single user account and have access to the same resources and operations as that user.

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 matches the capabilities of its associated user. 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.

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.

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 can perform any function on the site that you can, subject to the key's Workspace scope, including deleting 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.

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 Desktop/Mobile Session Lifetime controls these tokens' expiration. They 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. Choose the user account that will be in charge of S3 connections made with this key.

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.

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.