---
title: "Configuration"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Configuration}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The Synapse R Client can be configured either programmatically or by using a configuration file.

**Note:** The default configuration file does not need to be modified for most use-cases.

Create or edit the `.synapseConfig` file in your home directory to configure these settings. This file stores configuration options including your Synapse auth token, cache location, multi-threading settings, and storage credentials. See the [authentication](authentication.html) page for how to set up your credentials in this file.

For a reference showing the available settings and their meanings, see the full annotated example `.synapseConfig` in the [synapseclient GitHub repository](https://github.com/Sage-Bionetworks/synapsePythonClient/blob/develop/synapseclient/.synapseConfig).

## `.synapseConfig` sections

### `[default]` and `[profile <name>]`

Holds Synapse login credentials. `[default]` is used when no profile is specified; named profiles use `[profile <name>]` syntax. See the [authentication](authentication.html) vignette for full details including how to create tokens, select profiles, and use environment variables.

### `[sftp://hostname]`

Credentials for files stored on SFTP servers. Use one section per server; the section name is the full SFTP URL.

| Key | Description |
| --- | --- |
| `username` | Username for the SFTP server. |
| `password` | Password for the SFTP server. |

```ini
[sftp://some.sftp.url.com]
username = sftpuser
password = sftppassword
```

### `[https://s3.amazonaws.com/bucket_name]`

Credentials for files stored in AWS S3 or S3-compatible storage that Synapse does not manage access for. Use one section per bucket; the section name is the full endpoint URL including the bucket name.

| Key | Description |
| --- | --- |
| `profile_name` | Name of an AWS CLI profile from `~/.aws/credentials`. If omitted, the `default` AWS profile is used. |

```ini
[https://s3.amazonaws.com/bucket_name]
profile_name = local_credential_profile_name
```

For more information on AWS credentials files, see the [AWS CLI documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).

### `[cache]`

Downloaded files are cached to avoid repeat downloads of the same file.

| Key | Description |
| --- | --- |
| `location` | Path to the cache directory. Supports `~` and environment variables. Default: `~/.synapseCache`. |

```ini
[cache]
location = ~/.synapseCache
```

### `[debug]`

**Note:** Debug-level log output is not supported in `synapser`. The package initializes its underlying Python client with `debug=False` at load time, so this section has no effect regardless of what is configured here.

### `[endpoints]`

Override the default Synapse production service endpoints. Useful for testing against staging or development environments.

| Key | Description |
| --- | --- |
| `repoEndpoint` | Synapse repository REST API endpoint. |
| `authEndpoint` | Synapse authentication service endpoint. |
| `fileHandleEndpoint` | Synapse file service endpoint. |
| `portalEndpoint` | Synapse web portal URL. |

Note: The following are the default endpoints.

```ini
[endpoints]
repoEndpoint = https://repo-prod.prod.sagebase.org/repo/v1
authEndpoint = https://auth-prod.prod.sagebase.org/auth/v1
fileHandleEndpoint = https://file-prod.prod.sagebase.org/file/v1
portalEndpoint = https://www.synapse.org/
```

### `[transfer]`

Settings to configure how Synapse uploads and downloads data.

| Key | Description |
| --- | --- |
| `max_threads` | Number of concurrent threads/connections for file transfers. Applies to AWS S3 transfers (uploads and downloads). Default: `min(cpu_count + 4, 128)`. Maximum: `128`. Minimum: `1`. |
| `use_boto_sts` | If `true`, use AWS STS (Security Token Service) to obtain temporary credentials for S3 transfers instead of using stored AWS credentials directly. Valid values: `true` or `false` (case-insensitive). Default: `false`. |

```ini
[transfer]
max_threads = 16
use_boto_sts = false
```

**Note:** unlike the Python client, `synapser` does not currently expose a function to change `max_threads` programmatically after `synLogin()` — use the `.synapseConfig` file shown above to configure this value.