Authentication

There are two ways to authenticate: API Key authentication and Session-based authentication.

Authenticate with an API Key

Authenticating with an API key is the recommended authentication method for most scenarios, and is the method used in the examples on this site.

To use an API Key, first generate an API key from the web interface or via the API or an SDK.

Note that when using a user-specific API key, if the user is an administrator, you will have full access to the entire API. If the user is not an administrator, you will only be able to access files that user can access, and no access will be granted to site administration functions in the API.

Setting by Environment Variable on MacOS or Linux

export FILES_API_KEY="YOUR_API_KEY"

Setting by Environment Variable on Windows

set FILES_API_KEY="YOUR_API_KEY"

Example Request

files-cli --api-key=YOUR_API_KEY folders list-for ''
# After the key has been provided once it will be written to the files-cli configuration file.
# You do not need to include the same API key for future commands.

Authenticate with a Session

You can also authenticate by creating a user session using the username and password of an active user. If the user is an administrator, the session will have full access to all capabilities of Files.com. Sessions created from regular user accounts will only be able to access files that user can access, and no access will be granted to site administration functions.

Sessions use the exact same session timeout settings as web interface sessions. When a session times out, simply create a new session and resume where you left off. This process is not automatically handled by our SDKs because we do not want to store password information in memory without your explicit consent.

Logging In

To log in to the CLI App with your username and password, you must first configure the CLI App with information about your Files.com account.

Once you've specified your subdomain information and username, you do not need to specify it again for subsequent uses of the CLI App.

You will be prompted for the password when a command is run that requires authentication. Once the password is entered, subsequent calls will not require a password, unless the session is no longer valid (ie, expired).

Example Request

files-cli config set --subdomain SUBDOMAIN --username motor
files-cli folders list-for ''
> password: vroom

Using a Session

Once the password has been verified by the first run command, all subsequent commands can be run and the current verified session will be used.

You can also provide an existing session ID directly with --session-id, or store it with files-cli config set --session-id.

Example Request

files-cli folders list-for ''

# Or use an existing session ID directly.
files-cli --session-id=YOUR_SESSION_ID folders list-for ''

# You can also store the session ID for future commands.
files-cli config set --session-id YOUR_SESSION_ID

Logging Out

User sessions can be ended by calling sessions delete.

Example Request

files-cli sessions delete