# Connect to a Core

> Connect and authenticate a Python or TypeScript client with a Synnax Core: connect to Synnax Desktop, log in with arguments, an API key, or sy login, use TLS, and close the client.

Create a client to connect your code to a Synnax Core. The client logs in with an API key, or with the username and password of a [user](https://docs.synnaxlabs.com/reference/enterprise/users) on the Core.

## Connect to Synnax Desktop

Scripts on the same computer as Synnax Desktop can connect to its Core while it runs. Synnax Desktop saves the address of its Core and an API key in `~/.synnax/desktop.json`, which only your user can read. The Python client reads this file when you give no arguments:

```python
import synnax as sy

client = sy.Synnax()
```

When you also saved a login with [`sy login`](https://docs.synnaxlabs.com/reference/client/connect#log-in-once-with-sy-login), `sy.Synnax()` uses that login, not Synnax Desktop.

To get the code for each client, click the code button in the top bar of Synnax Desktop, or run the **Connect from code** command. The dialog shows the install command that matches the version of Synnax Desktop, and code that you can copy. The **TypeScript** tab gives code with the address and the API key filled in. Other clients, such as C++ and LabVIEW, can use the host, the port, and the API key from that code.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/client/connect/desktop/d716093b7038-dark.mp4#t=0.001)

When you close Synnax Desktop, its Core stops, and the connected scripts lose their connection. The API key stays the same the next time you open it. The port also stays the same, unless another program uses it.

To stop every script that uses the key, click **Reset key** in the dialog. Open streamers and writers stop with a [session ended](https://docs.synnaxlabs.com/reference/client/troubleshooting#session-ended) error. Python scripts that call `sy.Synnax()` use the new key the next time they start. Code that holds the old key needs the new one. **Erase all data** also deletes the key.

## Connect with arguments

**Python**

```python
import synnax as sy

client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
)
```

The client logs in when you create it. It raises `sy.AuthError` when the credentials are wrong. It raises `Unreachable`, from the `freighter` package, when it cannot reach the Core.

**TypeScript**

```typescript
import { Synnax } from "@synnaxlabs/client";

const client = new Synnax({
  host: "core.example.com",
  port: 9090,
  username: "operator",
  password: "secret",
});
await client.connect();
```

The client starts to connect when you create it, but it does not wait. `connect` waits for the connection. It throws `AuthError` when the credentials are wrong, and `DisconnectedError` when it cannot reach the Core. Without `connect`, the first request throws the same errors.

To keep credentials out of a script, read them from environment variables that you set. The clients read no environment variables by themselves.

## Connect with an API key

An API key lets a script log in with no password. The client gets the permissions of the user that owns the key. To get a key:

* **Synnax Desktop** -> the TypeScript code in the **Connect from code** dialog holds a key. See [Connect to Synnax Desktop](https://docs.synnaxlabs.com/reference/client/connect#connect-to-synnax-desktop).
* **A Core in Synnax Enterprise** -> in the Console, right-click a user in the users toolbar and select **Manage credentials**. Enter a key name, then click **Create key**. Copy the key at once: the Core does not show it again. See [Users](https://docs.synnaxlabs.com/reference/enterprise/users).
* **`sy login`** -> the command makes a key for you and saves it. See [Log in once with sy login](https://docs.synnaxlabs.com/reference/client/connect#log-in-once-with-sy-login).

**Python**

```python
import synnax as sy

client = sy.Synnax(
    host="core.example.com",
    port=9090,
    api_key="syk_...",
)
```

An API key needs a host. With an API key and no host, the client raises `sy.ValidationError`.

**TypeScript**

```typescript
import { Synnax } from "@synnaxlabs/client";

const client = new Synnax({
  host: "core.example.com",
  port: 9090,
  apiKey: "syk_...",
});
```

Give an API key or a username and password, not both. The client rejects a call that gives both. When someone deletes or resets the key, the client fails with an [invalid credentials](https://docs.synnaxlabs.com/reference/client/troubleshooting#invalid-credentials) error.

## Log in once with sy login

The `sy login` command saves an API key, so Python scripts can connect with no arguments. It is part of the Python client. Run it in a terminal:

```bash
sy login
```

Answer the prompts. Press **Enter** to keep the default in parentheses:

```plaintext
Enter your Synnax connection parameters:
Host (localhost): core.example.com
Port (9090):
Username (synnax): operator
Password:
Secure Connection? [y/n] (n):
```

When you answer `y` to the secure prompt, the command also asks for the “CA certificate path”. Enter the path to the `ca.crt` file of the Core. Leave it empty when the Core has a certificate from a public authority.

The command connects to the Core and prints “Connection successful!”. Then it makes an API key named “Python CLI on” and the name of your computer, saves the key, and prints “Saved an API key”. In your scripts, create the client with no arguments:

```python
import synnax as sy

client = sy.Synnax()
```

The command saves the host, port, TLS setting, and CA certificate path in `~/.synnax/config.json`. It saves the API key in the keychain of your operating system, under the name `synnax.api_key`. It does not save your username or password, and it deletes a password that an older version saved. In the Console, the key shows in **Manage credentials** for your user. When the login fails, the command saves nothing. Run `sy login` again to change the values.

With no saved login, `sy.Synnax()` connects to [Synnax Desktop](https://docs.synnaxlabs.com/reference/client/connect#connect-to-synnax-desktop). When neither is saved, it raises `sy.ValidationError`. When you give no host and no API key, the client ignores the other arguments and uses the saved login.

## Connect with TLS

When the Core serves TLS, set `secure` to true. For how to give the Core a certificate, see [Set up TLS](https://docs.synnaxlabs.com/reference/enterprise/tls).

**Python**

```python
client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
    secure=True,
)
```

The Python client checks the certificate of the Core, and checks that the certificate is for the host that you connect to. A certificate from a public authority, such as Let’s Encrypt, needs no setup. When the Core uses a self-signed certificate, give the path to its CA certificate in `ca_cert`:

```python
client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
    secure=True,
    ca_cert="/path/to/ca.crt",
)
```

A Core that you start with `--auto-cert` makes its own CA certificate. Give its path in `ca_cert`, or save it with [`sy login`](https://docs.synnaxlabs.com/reference/client/connect#log-in-once-with-sy-login). To find the file, see [Copy the CA certificate](https://docs.synnaxlabs.com/reference/enterprise/certificates#copy-the-ca-certificate).

**TypeScript**

```typescript
const client = new Synnax({
  host: "core.example.com",
  port: 9090,
  username: "operator",
  password: "secret",
  secure: true,
});
```

The TypeScript client checks the certificate of the Core. When the Core uses a self-signed certificate, the computer must trust its CA certificate. The TypeScript client has no CA certificate option. In a browser, [install the CA certificate](https://docs.synnaxlabs.com/reference/enterprise/certificates) on the computer. For Node.js, see [Node.js](https://docs.synnaxlabs.com/reference/enterprise/certificates#nodejs).

## Close the client

Close the client when your code is done with it:

**Python**

```python
client.close()
```

`close` also logs out. When the script exits without `close`, the client stops, but its session stays open on the Core until it times out.

**TypeScript**

```typescript
await client.close();
```

A Node.js script does not exit until you close the client.

## Client options

**Python**

* [`host`](https://docs.synnaxlabs.com/reference/client/connect#python-host)`str`

  The hostname or IP address of the Core. With no host, the client uses the values that `sy login` saved, or Synnax Desktop.

* [`port`](https://docs.synnaxlabs.com/reference/client/connect#python-port)`int`

  The port of the Core.

* [`api_key`](https://docs.synnaxlabs.com/reference/client/connect#python-api-key)`str`

  The API key to log in with. Needs a host. See [Connect with an API key](https://docs.synnaxlabs.com/reference/client/connect#connect-with-an-api-key).

* [`username`](https://docs.synnaxlabs.com/reference/client/connect#python-username)`str`

  The username to log in with.

* [`password`](https://docs.synnaxlabs.com/reference/client/connect#python-password)`str`

  The password to log in with.

* [`secure`](https://docs.synnaxlabs.com/reference/client/connect#python-secure)`bool = False`

  Connect with TLS.

* [`ca_cert`](https://docs.synnaxlabs.com/reference/client/connect#python-ca-cert)`str`

  The path to the CA certificate that signs the certificate of the Core. With `ca_cert` and no `secure`, the client raises `ValueError`. With no path, the client trusts the CA certificates of the computer.

* [`open_timeout`](https://docs.synnaxlabs.com/reference/client/connect#python-open-timeout)`TimeSpan | float = 5 s`

  How long to wait to open a connection. A number is seconds.

* [`read_timeout`](https://docs.synnaxlabs.com/reference/client/connect#python-read-timeout)`TimeSpan | float = 5 s`

  How long to wait for a response. A number is seconds.

* [`keep_alive`](https://docs.synnaxlabs.com/reference/client/connect#python-keep-alive)`TimeSpan | float = 30 s`

  How often the client pings the Core on each stream connection, such as the connection of a streamer or a writer. A number is seconds.

* [`max_retries`](https://docs.synnaxlabs.com/reference/client/connect#python-max-retries)`int = 3`

  How many times to retry a request that fails to reach the Core.

* [`clock_skew_threshold`](https://docs.synnaxlabs.com/reference/client/connect#python-clock-skew-threshold)`TimeSpan = 1 s`

  The largest difference between the clocks of the computer and the Core before the client prints a warning.

**TypeScript**

* [`host`](https://docs.synnaxlabs.com/reference/client/connect#typescript-host)`string`

  The hostname or IP address of the Core.

* [`port`](https://docs.synnaxlabs.com/reference/client/connect#typescript-port)`number | string`

  The port of the Core.

* [`apiKey`](https://docs.synnaxlabs.com/reference/client/connect#typescript-api-key)`string`

  The API key to log in with. See [Connect with an API key](https://docs.synnaxlabs.com/reference/client/connect#connect-with-an-api-key).

* [`username`](https://docs.synnaxlabs.com/reference/client/connect#typescript-username)`string`

  The username to log in with.

* [`password`](https://docs.synnaxlabs.com/reference/client/connect#typescript-password)`string`

  The password to log in with.

* [`secure`](https://docs.synnaxlabs.com/reference/client/connect#typescript-secure)`boolean = false`

  Connect with TLS.

* [`connectivityPollFrequency`](https://docs.synnaxlabs.com/reference/client/connect#typescript-connectivity-poll-frequency)`TimeSpan = 30 s`

  How often the client checks that it can reach the Core.

* [`clockSkewThreshold`](https://docs.synnaxlabs.com/reference/client/connect#typescript-clock-skew-threshold)`TimeSpan = 1 s`

  The largest difference between the clocks of the computer and the Core before the client prints a warning.

* [`name`](https://docs.synnaxlabs.com/reference/client/connect#typescript-name)`string`

  A name for the Core, which the client shows in its connection status messages.

* [`retry`](https://docs.synnaxlabs.com/reference/client/connect#typescript-retry)`object`

  How the client retries a request that fails to reach the Core: `baseInterval` (1 s), `maxInterval`, `maxRetries` (5), `scale` (1), and `jitter` (0).

* [`cache`](https://docs.synnaxlabs.com/reference/client/connect#typescript-cache)`boolean = true`

  Keep retrieved resources in memory and update them as they change on the Core.

* [`onRetry`](https://docs.synnaxlabs.com/reference/client/connect#typescript-on-retry)`function`

  Called each time the client retries a failed request. By default, the client logs a warning.

* [`onInternalError`](https://docs.synnaxlabs.com/reference/client/connect#typescript-on-internal-error)`function`

  Called with cache errors that have no caller to throw to. By default, the client logs the error.

When the client cannot connect, see [Troubleshooting](https://docs.synnaxlabs.com/reference/client/troubleshooting).
