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

Endpoint

GET/api_keys

Return Object

ApiKey[]

Authorization Requirement

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

Request Parameters

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

Additional Arguments

Example Request

curl "https://app.files.com/api/rest/v1/api_keys.json?user_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "id": 1,
    "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
    "description": "example",
    "created_at": "2000-01-01T01:00:00Z",
    "expires_at": "2000-01-01T01:00:00Z",
    "key": "[key]",
    "aws_style_credentials": true,
    "aws_access_key_id": "[aws_access_key_id]",
    "aws_secret_key": "[aws_secret_key]",
    "last_use_at": "2000-01-01T01:00:00Z",
    "name": "My Main API Key",
    "permission_set": "full",
    "platform": "win32",
    "site_id": 1,
    "site_name": "example",
    "url": "example",
    "user_id": 1,
    "workspace_id": 1
  }
]

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

Endpoint

GET/api_key

Return Object

ApiKey

Authorization Requirement

Available to all authenticated keys or sessions.

Example Request

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

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "description": "example",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "aws_style_credentials": true,
  "aws_access_key_id": "[aws_access_key_id]",
  "aws_secret_key": "[aws_secret_key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "name": "My Main API Key",
  "permission_set": "full",
  "platform": "win32",
  "site_id": 1,
  "site_name": "example",
  "url": "example",
  "user_id": 1,
  "workspace_id": 1
}

Show API Key

Endpoint

GET/api_keys/{id}

Return Object

ApiKey

Authorization Requirement

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

Request Parameters

Parameter	Description
id int64 Required	Api Key ID.

Example Request

curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "description": "example",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "aws_style_credentials": true,
  "aws_access_key_id": "[aws_access_key_id]",
  "aws_secret_key": "[aws_secret_key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "name": "My Main API Key",
  "permission_set": "full",
  "platform": "win32",
  "site_id": 1,
  "site_name": "example",
  "url": "example",
  "user_id": 1,
  "workspace_id": 1
}

Create API Key

Endpoint

POST/api_keys

Return Object

ApiKey

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Default	Description
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	`false`	If `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	`0`	Workspace ID for this API Key. `0` means the default workspace.

Example Request

curl https://app.files.com/api/rest/v1/api_keys.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"description":"example","expires_at":"2000-01-01T01:00:00Z","name":"My Main API Key","aws_style_credentials":true,"path":"shared/docs","permission_set":"full","workspace_id":1}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "description": "example",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "aws_style_credentials": true,
  "aws_access_key_id": "[aws_access_key_id]",
  "aws_secret_key": "[aws_secret_key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "name": "My Main API Key",
  "permission_set": "full",
  "platform": "win32",
  "site_id": 1,
  "site_name": "example",
  "url": "example",
  "user_id": 1,
  "workspace_id": 1
}

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

Endpoint

PATCH/api_key

Return Object

ApiKey

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

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

curl https://app.files.com/api/rest/v1/api_key.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"expires_at":"2000-01-01T01:00:00Z","name":"My Main API Key","permission_set":"full"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "description": "example",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "aws_style_credentials": true,
  "aws_access_key_id": "[aws_access_key_id]",
  "aws_secret_key": "[aws_secret_key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "name": "My Main API Key",
  "permission_set": "full",
  "platform": "win32",
  "site_id": 1,
  "site_name": "example",
  "url": "example",
  "user_id": 1,
  "workspace_id": 1
}

Update API Key

Endpoint

PATCH/api_keys/{id}

Return Object

ApiKey

Authorization Requirement

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

Request Parameters

Parameter	Description
id int64 Required	Api Key ID.
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

curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"description":"example","expires_at":"2000-01-01T01:00:00Z","name":"My Main API Key"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "description": "example",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "aws_style_credentials": true,
  "aws_access_key_id": "[aws_access_key_id]",
  "aws_secret_key": "[aws_secret_key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "name": "My Main API Key",
  "permission_set": "full",
  "platform": "win32",
  "site_id": 1,
  "site_name": "example",
  "url": "example",
  "user_id": 1,
  "workspace_id": 1
}

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

Endpoint

DELETE/api_key

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Example Request

curl https://app.files.com/api/rest/v1/api_key.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Delete API Key

Endpoint

DELETE/api_keys/{id}

Return Object

No return value.

Authorization Requirement

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

Request Parameters

Parameter	Description
id int64 Required	Api Key ID.

Example Request

curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

The ApiKey Object

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

Attribute	Description
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.

Example ApiKey Object

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "description": "example",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "aws_style_credentials": true,
  "aws_access_key_id": "[aws_access_key_id]",
  "aws_secret_key": "[aws_secret_key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "name": "My Main API Key",
  "permission_set": "full",
  "platform": "win32",
  "site_id": 1,
  "site_name": "example",
  "url": "example",
  "user_id": 1,
  "workspace_id": 1
}

API Keys

Endpoint

Return Object

Authorization Requirement

Request Parameters

Additional Arguments

Pagination

Sorting

Filtering

Endpoint

Return Object

Authorization Requirement

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Endpoint

Return Object

Authorization Requirement

Request Parameters