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.

Set Config.APIKey and initialize the configuration before passing it to a resource client. This configuration applies to that client.

API Key Authentication

import (
    "fmt"
    "errors"

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

config := files_sdk.Config{APIKey: "YOUR_API_KEY"}.Init()
client := folder.Client{Config: config}
it, err := client.ListFor(files_sdk.FolderListForParams{})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

for file, err := range it.All() {
    if err != nil {
        var respErr files_sdk.ResponseError
        if errors.As(err, &respErr) {
            fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
        } else {
            fmt.Printf("Request failed: %v\n", err)
        }
        return
    }
    fmt.Println(file.Path)
}

You can reuse files_sdk.GlobalConfig by passing it to a client, for example folder.Client{Config: files_sdk.GlobalConfig}.

To use the FILES_API_KEY environment variable, leave Config.APIKey empty. Package-level resource functions also read this variable:

API Key From the Environment

import (
    "fmt"
    "errors"

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

it, err := folder.ListFor(files_sdk.FolderListForParams{})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

for file, err := range it.All() {
    if err != nil {
        var respErr files_sdk.ResponseError
        if errors.As(err, &respErr) {
            fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
        } else {
            fmt.Printf("Request failed: %v\n", err)
        }
        return
    }
    fmt.Println(file.Path)
}

Noteworthy

Don't forget to replace the placeholder, YOUR_API_KEY, with your actual API key.

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 follow the same timeout settings as web sessions. When a session expires, create a new session and update the clients that use it. The SDK does not renew sessions automatically.

Logging In

Create a session.Client with your Files.com subdomain, then call Create with your username and password. Use the returned session ID as Config.SessionId when creating resource clients.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/folder"
    "github.com/Files-com/files-sdk-go/v3/session"
)

sessionClient := session.Client{Config: files_sdk.Config{Subdomain: "MY-SUBDOMAIN"}.Init()}
thisSession, err := sessionClient.Create(files_sdk.SessionCreateParams{Username: "USERNAME", Password: "PASSWORD"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

config := files_sdk.Config{Subdomain: "MY-SUBDOMAIN", SessionId: thisSession.Id}.Init()
folderClient := folder.Client{Config: config}

it, err := folderClient.ListFor(files_sdk.FolderListForParams{})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

for file, err := range it.All() {
    if err != nil {
        var respErr files_sdk.ResponseError
        if errors.As(err, &respErr) {
            fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
        } else {
            fmt.Printf("Request failed: %v\n", err)
        }
        return
    }
    fmt.Println(file.Path)
}

Using a Session

Set Config.SessionId to the session's Id and pass the configuration to each resource client that uses the session.

Example Request

import (
    "fmt"
    "errors"

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

config := files_sdk.Config{Subdomain: "MY-SUBDOMAIN", SessionId: thisSession.Id}.Init()
folderClient := folder.Client{Config: config}

it, err := folderClient.ListFor(files_sdk.FolderListForParams{})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

for file, err := range it.All() {
    if err != nil {
        var respErr files_sdk.ResponseError
        if errors.As(err, &respErr) {
            fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
        } else {
            fmt.Printf("Request failed: %v\n", err)
        }
        return
    }
    fmt.Println(file.Path)
}

Logging Out

User sessions can be ended by calling Delete() on the Session client.

Example Request

import (
    "fmt"
    "errors"

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

sessionClient := session.Client{Config: files_sdk.Config{SessionId: thisSession.Id}.Init()}
err := sessionClient.Delete()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}