Authentication

Comprehensive guide for authenticating Synnax clients.

This guide covers all authentication methods and connection parameters for the Synnax clients. If you’re looking for a quick start, check out the Quick start guide instead.

Authentication methods

There are three ways to authenticate with a Synnax Core: using the CLI to permanently store your credentials, passing your credentials directly to the client, or configuring environment variables.

For instructions on direct authentication, see Create a Client.
CLI authentication is only supported in the Python client.

Parameter	Description
`host`	The hostname of the Synnax Core
`port`	The port of the Synnax Core
`username`	The username to authenticate with
`password`	The password to authenticate with.
`secure`	Whether to use TLS encryption.
`ca_cert`	Python only. The path to the CA certificate of a secure Core.

CLI authentication (Python only)

The easiest way to authenticate with a Core is with the login command. This will permanently store your credentials in the operating system’s keychain.

This method is highly recommended, as it makes it easy to share scripts without accidentally revealing credentials.

In the terminal, run the following command:

sy login

If you get the error command not found, see our troubleshooting guide.

The CLI will prompt for additional information:

Enter your Synnax connection parameters:
Host (localhost): # YOUR HOST
Port (9090): # YOUR PORT
Username (synnax): # YOUR USERNAME
Password: # YOUR PASSWORD
Secure connection? (y/n) (n):
CA certificate path (empty for system roots): # ONLY FOR A SECURE CONNECTION

You should then see the following message:

Saved credentials. You can now use the Synnax Client
without having to log in. To connect to the Core in a Python shell, use the following:

from synnax import Synnax
client = Synnax()

Connecting to a secure Core (Python only)

With secure=True, the Python client verifies the Core’s certificate against the operating system’s trust store. A certificate from a public authority such as Let’s Encrypt needs no further setup. Connect using the host name the certificate was issued for.

A Core started with --auto-cert signs its certificate with its own CA. Give the client the path to that CA certificate (ca.crt in the Core’s --certs-dir) at the sy login prompt, or pass it with ca_cert:

client = sy.Synnax(
    host="synnax.example.com",
    port=9090,
    username="synnax",
    password="seldon",
    secure=True,
    ca_cert="/path/to/ca.crt",
)

Environment variables

You can store your connection parameters as environment variables to keep them out of your code. This is useful for production deployments or when working with multiple environments.

Setting environment variables

Select your operating system below to see how to set environment variables:

export SYNNAX_HOST="localhost"
export SYNNAX_PORT="9090"
export SYNNAX_USERNAME="synnax"
export SYNNAX_PASSWORD="seldon"
export SYNNAX_SECURE="false"

PowerShell:

$env:SYNNAX_HOST="localhost"
$env:SYNNAX_PORT="9090"
$env:SYNNAX_USERNAME="synnax"
$env:SYNNAX_PASSWORD="seldon"
$env:SYNNAX_SECURE="false"

Command Prompt:

set SYNNAX_HOST=localhost
set SYNNAX_PORT=9090
set SYNNAX_USERNAME=synnax
set SYNNAX_PASSWORD=seldon
set SYNNAX_SECURE=false

export SYNNAX_HOST="localhost"
export SYNNAX_PORT="9090"
export SYNNAX_USERNAME="synnax"
export SYNNAX_PASSWORD="seldon"
export SYNNAX_SECURE="false"

Using environment variables in code

import os
import synnax as sy

client = sy.Synnax(
    host=os.environ["SYNNAX_HOST"],
    port=int(os.environ["SYNNAX_PORT"]),
    username=os.environ["SYNNAX_USERNAME"],
    password=os.environ["SYNNAX_PASSWORD"],
    secure=os.environ.get("SYNNAX_SECURE", "false").lower() == "true"
)

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

const client = new Synnax({
  host: process.env.SYNNAX_HOST!,
  port: parseInt(process.env.SYNNAX_PORT ?? "9090"),
  username: process.env.SYNNAX_USERNAME!,
  password: process.env.SYNNAX_PASSWORD!,
  secure: process.env.SYNNAX_SECURE === "true",
});

Quick start

Channels