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.

Example Request

\Files\Files::setApiKey('YOUR_API_KEY');

try {
  # Alternatively, you can specify the API key on a per-object basis in the second parameter to a model constructor.
  $user = new \Files\Model\User($params, array('api_key' => 'YOUR_API_KEY'));
  
  # You may also specify the API key on a per-request basis in the final parameter to static methods.
  \Files\Model\User::find($id, $params, array('api_key' => 'YOUR_API_KEY'));
} catch (\Files\NotAuthenticated\InvalidUsernameOrPasswordException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}

Noteworthy

Don't forget to replace the placeholder, YOUR_API_KEY, with your actual 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, the create method is called on the \Files\Model\Session object with the user's username and password.

This returns a session object that can be used to authenticate SDK method calls.

Example Request

try {
  $session = \Files\Model\Session::create(['username' => 'motor', 'password' => 'vroom']);
} catch (\Files\NotAuthenticated\InvalidUsernameOrPasswordException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}

Using a Session

Once a session has been created, you can store the session globally, use the session per object, or use the session per request to authenticate SDK operations.

Example Request

# You may set the returned session ID to be used by default for subsequent requests.
\Files\Files::setSessionId($session->id);

try {
  # Alternatively, you can specify the session ID on a per-object basis in the second parameter to a model constructor.
  $user = new \Files\Model\User($params, array('session_id' => $session->id));
  
  # You may also specify the session ID on a per-request basis in the final parameter to static methods.
  \Files\Model\User::find($id, $params, array('session_id' => $session->id));
} catch (\Files\NotAuthenticated\InvalidUsernameOrPasswordException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}

Logging Out

User sessions can be ended by calling the Session::destroy method.

Example Request

try {
  \Files\Model\Session::destroy();
} catch (\Files\NotAuthenticated\InvalidUsernameOrPasswordException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}