API Keys

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

API keys use the owning user's permissions, narrowed by the key's permission set, workspace scope, and any folder path restriction. 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.

Set path when creating a key to limit file and folder access to that folder and its descendants. Except for office_integration keys, the path does not need to exist when the key is created. The restriction applies to the files, folders, and file_actions endpoints, on every path those requests access, including both source and destination paths for copy and move operations. Requests to those endpoints outside the restriction are denied with not-authorized/api-key-is-path-restricted. It never grants additional access to the owning user. A key with the files_only permission set can use only those endpoints, plus GET /file_migrations/{id} to follow file operations under the visibility rules below and GET /api_key to read its own record. Every other endpoint denies a files_only key with not-authorized/api-key-only-for-file-operations.

On GET /file_migrations/{id}, any key with a path can read only migrations it started. Without a path, user-owned keys retain their user-scoped access, including Desktop and Mobile keys in the owning user's Workspace. A site-wide key bound to a Workspace can read a migration only when its source and destination are both in that Workspace. Workspace binding applies to every files_only key, including Workspace 0, and to full-access keys in a named Workspace. A full-access site-wide key in the default Workspace can read migrations across the Site. Migrations outside the caller's visibility return not-found.

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

[]*ApiKey

Authorization Requirement

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

ApiKeyListParams Fields

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

Additional Arguments

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

apiKeyIterator, err := api_key.List(files_sdk.ApiKeyListParams{UserId: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for apiKeyIterator.Next() {
    apiKey := apiKeyIterator.apiKey()
}
err = apiKeyIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

apiKey, err := api_key.FindCurrent()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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.

ApiKeyFindParams Fields

FieldDescription
Id
int64
Required		Api Key ID.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

apiKey, err := api_key.Find(files_sdk.ApiKeyFindParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Create API Key

SDK Method

apikey.Create()

Return Object

ApiKey

Authorization Requirement

Available to all authenticated keys or sessions.

ApiKeyCreateParams Fields

FieldDefaultDescription
UserId
int64		User ID. Provide a value of 0 to operate the current session's user.
Description
string		User-supplied description of API key.
ExpiresAt
string		API Key expiration date
Name
string
Required		""Internal name for the API Key. For your use.
AwsStyleCredentials
boolean		falseIf true, this API key will be usable with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
Path
string		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. Other endpoints do not apply the path restriction; use the files_only permission set to confine a key to file operations and their supporting lookups. Does not grant access beyond the owning user's permissions. Optional except for office_integration keys, which require a path the owning user can read.
PermissionSet
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 use only the files, folders, and file_actions endpoints, 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, and every other endpoint denies them with not-authorized/api-key-only-for-file-operations.
Possible values: none, full, desktop_app, sync_app, office_integration, mobile_app, files_only
WorkspaceId
int64		0Workspace ID for this API Key. 0 means the default workspace.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

apiKey, err := api_key.Create(files_sdk.ApiKeyCreateParams{Name: "My Main API Key"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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.

ApiKeyUpdateCurrentParams Fields

FieldDescription
ExpiresAt
string		API Key expiration date
Name
string		Internal name for the API Key. For your use.
PermissionSet
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 use only the files, folders, and file_actions endpoints, 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, and every other endpoint denies them with not-authorized/api-key-only-for-file-operations.
Possible values: none, full, desktop_app, sync_app, office_integration, mobile_app, files_only

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

apiKey, err := api_key.UpdateCurrent(files_sdk.ApiKeyUpdateCurrentParams{ExpiresAt: "2000-01-01T01:00:00Z"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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.

ApiKeyUpdateParams Fields

FieldDescription
Id
int64
Required		Api Key ID.
Description
string		User-supplied description of API key.
ExpiresAt
string		API Key expiration date
Name
string		Internal name for the API Key. For your use.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

apiKey, err := api_key.Update(files_sdk.ApiKeyUpdateParams{
  Id: 1,
  Description: "example"
})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

err := api_key.DeleteCurrent()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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.

ApiKeyDeleteParams Fields

FieldDescription
Id
int64
Required		Api Key ID.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    api_key "github.com/Files-com/files-sdk-go/v3/apikey"
)

err := api_key.Delete(files_sdk.ApiKeyDeleteParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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
DescriptiveLabel
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.
CreatedAt
date-time		Time which API Key was created
ExpiresAt
date-time		API Key expiration date
Key
string		API Key actual key string
AwsStyleCredentials
boolean		If true, this API key will be usable with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
AwsAccessKeyId
string		AWS Access Key ID to use with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
AwsSecretKey
string		AWS Secret Key to use with AWS-compatible endpoints, such as our Inbound S3-compatible endpoint.
LastUseAt
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.
PermissionSet
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 use only the files, folders, and file_actions endpoints, 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, and every other endpoint denies them with not-authorized/api-key-only-for-file-operations.
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?
SiteId
int64		Site ID
SiteName
string		Site Name
Url
string		URL for API host.
UserId
int64		User ID for the owner of this API Key. May be blank for Site-wide API Keys.
WorkspaceId
int64		Workspace ID for this API Key. 0 means the default workspace.