ConnectionInfo — Calimero Client Py

create_connection()

The preferred way to create a ConnectionInfo is via the module-level factory function.

import calimero

conn = calimero.create_connection(
api_url="https://node.example.com",
node_name="prod-node" # optional, but recommended
)

api_url

str

Full URL of the Calimero node, e.g. https://test.merod.dev.p2p.aws.calimero.network. Must be a valid URL — raises ValueError if malformed.

node_name

str | None

A stable, unique identifier for this node. Used as a key when caching JWT tokens to disk. Use the same name across sessions to reuse cached credentials. Defaults to None.

Properties

.api_url

str — The base URL the connection is pointed at.

.node_name

str | None — The name assigned at construction for token caching.

Methods

detect_auth_mode()

Probes the node to determine whether authentication is required. Returns an AuthMode object.

mode = conn.detect_auth_mode()
if mode.value == "required":
print("Node requires authentication")

get(path)

Makes a raw authenticated GET request to the node at the given path. Returns a Python dict/list (deserialized from JSON). Useful for accessing endpoints not yet wrapped by Client.

data = conn.get("/admin-api/health")

Token Caching

When node_name is provided, JWT tokens are cached to disk under ~/.merobox/auth_cache/. The filename is derived from a hash of the node name to keep it stable and unique.

get_token_cache_dir()

Returns the path to the token cache directory as a string.

dir = calimero.get_token_cache_dir()
# e.g. /home/user/.merobox/auth_cache

get_token_cache_path(node_name)

Returns the full path to the cached token file for a specific node name. Same input always produces the same output.

path = calimero.get_token_cache_path("prod-node")
# ~/.merobox/auth_cache/prod-node-a1b2c3.json

!

Use stable node names

Use the same node_name across all sessions to ensure cached tokens are found and reused. A different name each run (e.g. using a UUID) defeats caching and forces a re-authentication every time.