API Keys

An APIKey is a key that allows programmatic access to your Site.

API keys confer all the permissions of the user who owns them unless the key uses a restricted permission set. If an API key is created without a user owner, it is considered a site-wide API key. Site-wide API keys with the files_only permission set are restricted to file-user permissions and workspace scoping.

We recommend registering API keys to service users wherever possible and then using User or Group Permissions to restrict that API Key appropriately.

List API Keys

SDK Method

ApiKey.List();

Return Object

FilesList<ApiKey>

Authorization Requirement

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Method Arguments

ArgumentDescription
user_id
int64		User ID. Provide a value of 0 to operate the current session's user.

Additional Arguments

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("user_id", (Int64?) 1);

try
{
    var apiKeyIterator = ApiKey.List(parameters);
    foreach (ApiKey apiKey in apiKeyIterator.ListAutoPaging()) {
        // Operate on apiKey
    }
}
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);
}

Show information about current API key. (Requires current API connection to be using an API key.)

SDK Method

ApiKey.FindCurrent();

Return Object

ApiKey

Authorization Requirement

Available to all authenticated keys or sessions.

Example Request

using FilesCom.Models;

try
{
    var apiKey = await ApiKey.FindCurrent();
    // Operate on apiKey
}
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);
}

Show API Key

SDK Method

ApiKey.Find();

Return Object

ApiKey

Authorization Requirement

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Method Arguments

ArgumentDescription
id
int64
Required		Api Key ID.

Example Request

using FilesCom.Models;

try
{
    var apiKey = await ApiKey.Find(id);
    // Operate on apiKey
}
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);
}

Create API Key

SDK Method

ApiKey.Create();

Return Object

ApiKey

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDefaultDescription
user_id
int64		User ID. Provide a value of 0 to operate the current session's user.
description
string		User-supplied description of API key.
expires_at
string		API Key expiration date
name
string
Required		""Internal name for the API Key. For your use.
aws_style_credentials
boolean		falseIf true, this API key will be usable with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
path
string		Folder path restriction for office_integration permission set API keys.
permission_set
string		"full"Permissions for this API Key. Keys with the desktop_app permission set only have the ability to do the functions provided in our Desktop App (File and Share Link operations). Keys with the office_integration permission set are auto generated, and automatically expire, to allow users to interact with office integration platforms. Keys with the files_only permission set can perform file operations as a full-access file user in the key's workspace scope, but cannot use site admin, workspace admin, folder admin, group admin, partner admin, or billing privileges from the owning user.
Possible values: none, full, desktop_app, sync_app, office_integration, mobile_app, files_only
workspace_id
int64		0Workspace ID for this API Key. 0 means the default workspace.

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("name", "My Main API Key");

try
{
    var apiKey = await ApiKey.Create(parameters);
    // Operate on apiKey
}
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);
}

Update current API key. (Requires current API connection to be using an API key.)

SDK Method

ApiKey.UpdateCurrent();

Return Object

ApiKey

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
expires_at
string		API Key expiration date
name
string		Internal name for the API Key. For your use.
permission_set
string		Permissions for this API Key. Keys with the desktop_app permission set only have the ability to do the functions provided in our Desktop App (File and Share Link operations). Keys with the office_integration permission set are auto generated, and automatically expire, to allow users to interact with office integration platforms. Keys with the files_only permission set can perform file operations as a full-access file user in the key's workspace scope, but cannot use site admin, workspace admin, folder admin, group admin, partner admin, or billing privileges from the owning user.
Possible values: none, full, desktop_app, sync_app, office_integration, mobile_app, files_only

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("expires_at", "2000-01-01T01:00:00Z");

try
{
    var apiKey = await ApiKey.UpdateCurrent(parameters);
    // Operate on apiKey
}
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);
}

Update API Key

SDK Method

apiKey.Update();

Return Object

ApiKey

Authorization Requirement

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Method Arguments

ArgumentDescription
description
string		User-supplied description of API key.
expires_at
string		API Key expiration date
name
string		Internal name for the API Key. For your use.

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("description", "example");

try
{
    // Find the apiKey object by its id.
    var apiKey = await ApiKey.Find(id);
    await apiKey.Update(parameters);
}
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);
}

Delete current API key. (Requires current API connection to be using an API key.)

SDK Method

ApiKey.DeleteCurrent();

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Example Request

using FilesCom.Models;

try
{
    await ApiKey.DeleteCurrent();
}
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);
}

Delete API Key

SDK Method

apiKey.Delete();

Return Object

No return value.

Authorization Requirement

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Example Request

using FilesCom.Models;

try
{
    // Find the apiKey object by its id.
    var apiKey = await ApiKey.Find(id);
    await apiKey.Delete();
}
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);
}

The ApiKey Object

Some of the methods above return a ApiKey object. The attributes of this object are listed below.

AttributeDescription
id
int64		API Key ID
descriptive_label
string		Unique label that describes this API key. Useful for external systems where you may have API keys from multiple accounts and want a human-readable label for each key.
description
string		User-supplied description of API key.
created_at
date-time		Time which API Key was created
expires_at
date-time		API Key expiration date
key
string		API Key actual key string
aws_style_credentials
boolean		If true, this API key will be usable with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
aws_access_key_id
string		AWS Access Key ID to use with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
aws_secret_key
string		AWS Secret Key to use with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
last_use_at
date-time		API Key last used - note this value is only updated once per 3 hour period, so the 'actual' time of last use may be up to 3 hours later than this timestamp.
name
string		Internal name for the API Key. For your use.
permission_set
string		Permissions for this API Key. Keys with the desktop_app permission set only have the ability to do the functions provided in our Desktop App (File and Share Link operations). Keys with the office_integration permission set are auto generated, and automatically expire, to allow users to interact with office integration platforms. Keys with the files_only permission set can perform file operations as a full-access file user in the key's workspace scope, but cannot use site admin, workspace admin, folder admin, group admin, partner admin, or billing privileges from the owning user.
Possible values: none, full, desktop_app, sync_app, office_integration, mobile_app, files_only
platform
string		If this API key represents a Desktop app, what platform was it created on?
site_id
int64		Site ID
site_name
string		Site Name
url
string		URL for API host.
user_id
int64		User ID for the owner of this API Key. May be blank for Site-wide API Keys.
workspace_id
int64		Workspace ID for this API Key. 0 means the default workspace.