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.

You may provide the key to the API one of two ways. The simplest way is to set the X-FilesAPI-Key header with the value of the key.

Alternatively, you may use HTTP Basic Authentication. You should pass in the API Key as the Username field in HTTP Basic Authentication. The password field may be left blank, or you may use a placeholder value, such as x.

Example Request

curl https://SUBDOMAIN.files.com/api/rest/v1/users.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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 create a session, a POST request is made to /sessions with the user's username and password.

The id field in the response is the session ID that must be provided to subsequent requests in order to use this session.

Endpoint

POST/sessions

Example Request

curl https://SUBDOMAIN.files.com/api/rest/v1/sessions.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"username": "motor", "password": "vroom"}'

Example Response

{
  "id": "8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599"
}

Using a Session

Once a session has been created, you authenticate to the REST API by sending a header called X-FilesAPI-Auth set to the value of the session ID.

Example Request

curl https://SUBDOMAIN.files.com/api/rest/v1/users.json \
  -H 'X-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599'

Logging Out

User sessions can be ended by sending a DELETE request to /sessions. If a valid user session ID is passed in via the X-FilesAPI-Auth header, then that user session will be deleted, which is similar to the user logging out. Note that sending a DELETE request at this endpoint will always result in a response of an empty array, even if an invalid user session was passed in.

Endpoint

DELETE/sessions

Example Request

curl https://SUBDOMAIN.files.com/api/rest/v1/sessions.json \
  -H 'X-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599' \
  -X DELETE

Example Response

[]

Reauthentication

If authenticating to the API via a session ID (as opposed to an API key), we require that you provide the session user's password again in a X-Files-Reauthentication header for certain types of requests where we want to add an additional level of security. We call this process Reauthentication.

Currently, reauthentication is required for the following actions:

  • Changing the password of a User
  • Deleting a User

Example Request

curl https://SUBDOMAIN.files.com/api/rest/v1/users/123.json \
  -X PUT \
  -H 'Content-Type: application/json' \
  -H 'X-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599' \
  -H 'X-Files-Reauthentication: password:YourPasswordHere' \
  -d '{"password": "NewPassword"}'