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.

A user key follows its account's permissions, narrowed by the key's permission scope, Workspace, and any path restriction on file operations. It can perform administrative operations only when both the account and key permit them. API Keys explains credential scope and lifecycle; Workspaces explains request context and delegated administration.

Example Request

using FilesCom;
using FilesCom.Models;

// Using manual configuration
var config = new FilesConfiguration();
config.ApiKey = "YOUR_API_KEY";

// ...as the default client, which static methods such as User.Find use
new FilesClient(config);

// ...or as an independent client, used through its properties such as client.Users
FilesClient client = FilesClient.Create(config);

app.config

<configSections>
    <sectionGroup name="files.com">
        <section
            name="filesConfiguration"
            type="FilesCom.FilesConfiguration, FilesCom"
        />
    </sectionGroup>
</configSections>
<files.com>
    <filesConfiguration ApiKey="YOUR_API_KEY" />
</files.com>

Example Request Using app.config

// Using the configuration in app.config
new FilesClient();

// You may also specify the API key on a per-request basis in the options parameter.
var options = new Dictionary<string, object>();
options.Add("api_key", "YOUR_API_KEY");

try
{
    User user = await User.Find(id, null, options);
    User sameUser = await client.Users.FindAsync(id, null, options);
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

Authenticate with a Session

Create a session with the username and password of an active user. The session uses that user's permissions, including any delegated administrative access. Workspaces describes account scope and administrative access.

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 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

using FilesCom;
using FilesCom.Models;

Dictionary<string, object> paramsDict = new Dictionary<string, object>();
FilesClient client = FilesClient.Create(filesConfig);
paramsDict.Add("username", "username");
paramsDict.Add("password", "password");

try
{
    Session session = await client.Sessions.CreateAsync(paramsDict);
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

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

using FilesCom;
using FilesCom.Models;

// You may make a client that uses the returned session for all of its requests,
// or pass the configuration to new FilesClient to make it the default for static methods.
FilesConfiguration sessionConfig = new FilesConfiguration();
sessionConfig.SessionId = session.Id;
FilesClient sessionClient = FilesClient.Create(sessionConfig);

// Alternatively, you can specify the session ID on a per-object basis
// in the second parameter to a model constructor.
Dictionary<string, object> optionsDict = new Dictionary<string, object>();
optionsDict.Add("session_id", session.Id);
User user = new User(new Dictionary<string, object>(), optionsDict);

// You may also specify the session ID on a per-request basis in the options parameter.
try
{
    await sessionClient.Folders.ListFor("/").AllAsync();
    await client.Folders.ListFor("/", null, optionsDict).AllAsync();
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

Logging Out

User sessions can be ended calling the destroy method on the session object.

Example Request

using FilesCom.Models;

try
{
    await Session.Destroy();
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}