FIfiles
user
API Keys

Create API Key

Changed on

Create API Key

post/user/api_keys

Request

  • Base URL
    https://app.files.com/api/rest/v1
  • URL
    https://app.files.com/api/rest/v1/user/api_keys
  • Auth
    none declared

Request body multipart/form-data

user_idinteger

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

descriptionstring

User-supplied description of API key.

expires_atstring date-time

API Key expiration date

namestring required

Internal name for the API Key. For your use.

aws_style_credentialsboolean

If true, this API key will be usable with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.

pathstring

Restricts the file and folder operations made with this key, meaning the files, folders, and file_actions endpoints, to the specified folder and its descendants, including copy and move destinations. For GET /file_migrations/{id}, a key with a path can read only migrations it started. Does not grant access beyond the owning user's permissions. Optional for files_only keys and required for office_integration keys, which need a path the owning user can read. Keys with any other permission set cannot have a path.

permission_set'none' | 'full' | 'desktop_app' | 'sync_app' | 'office_integration' | 'mobile_app' | 'files_only'

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 mobile_app permission set can only perform the functions provided by our Mobile 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 use only the files, folders, and file_actions endpoints, excluding the GPG Encrypt and GPG Decrypt file actions, where they perform file operations as a full-access file user in the key's workspace scope, along with GET /file_migrations/{id} and GET /api_key. On the migration lookup, any key with a path can read only migrations it started. Without a path, user-owned keys retain user-scoped access; site-wide Workspace-bound keys can read only migrations whose source and destination are both in their Workspace. Every files_only key is Workspace-bound, including Workspace 0, as is a full-access key in a named Workspace. A full-access site-wide key in the default Workspace retains Site-wide migration access. Migrations outside the caller's visibility return not-found. Keys with files_only cannot use site admin, workspace admin, folder admin, group admin, partner admin, or billing privileges from the owning user. Both GPG file actions and every other endpoint deny them with not-authorized/api-key-only-for-file-operations. Folder-configured GPG encryption and decryption still apply to files uploaded with a files_only key.

workspace_idinteger

Workspace ID for this API Key. 0 means the default workspace.

Example request

{
  "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
}

Response

The ApiKeys object.

idinteger

API Key ID

descriptive_labelstring

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.

descriptionstring

User-supplied description of API key.

created_atstring date-time

Time which API Key was created

expires_atstring date-time

API Key expiration date

keystring

API Key actual key string

aws_style_credentialsboolean

If true, this API key will be usable with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.

aws_access_key_idstring

AWS Access Key ID to use with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.

aws_secret_keystring

AWS Secret Key to use with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.

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

namestring

Internal name for the API Key. For your use.

permission_set'none' | 'full' | 'desktop_app' | 'sync_app' | 'office_integration' | 'mobile_app' | 'files_only'

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 mobile_app permission set can only perform the functions provided by our Mobile 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 use only the files, folders, and file_actions endpoints, excluding the GPG Encrypt and GPG Decrypt file actions, where they perform file operations as a full-access file user in the key's workspace scope, along with GET /file_migrations/{id} and GET /api_key. On the migration lookup, any key with a path can read only migrations it started. Without a path, user-owned keys retain user-scoped access; site-wide Workspace-bound keys can read only migrations whose source and destination are both in their Workspace. Every files_only key is Workspace-bound, including Workspace 0, as is a full-access key in a named Workspace. A full-access site-wide key in the default Workspace retains Site-wide migration access. Migrations outside the caller's visibility return not-found. Keys with files_only cannot use site admin, workspace admin, folder admin, group admin, partner admin, or billing privileges from the owning user. Both GPG file actions and every other endpoint deny them with not-authorized/api-key-only-for-file-operations. Folder-configured GPG encryption and decryption still apply to files uploaded with a files_only key.

platformstring

If this API key represents a Desktop app, what platform was it created on?

site_idinteger

Site ID

site_namestring

Site Name

urlstring

URL for API host.

user_idinteger

User ID for the owner of this API Key. May be blank for Site-wide API Keys.

workspace_idinteger

Workspace ID for this API Key. 0 means the default workspace.

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
}

Changes