Configuration

Bitween reads standard .NET configuration: appsettings.json, appsettings.{Environment}.json, environment variables and command-line arguments. In environment variable names, replace : with a double underscore, as in Bitween__DatabaseType.

Some values are also runtime settings that administrators change in the UI. Once stored, a setting ignores configuration. See Runtime settings.

Required#

The service stops at startup with a clear error when the database connection string is missing.

Set these too when they apply:

• Other applications publish to Bitween's bus: Bus:OnInvalidUserToken. See Bus messages from other applications.
• Upgrading, and partners must keep getting one call at a time, in order: Bitween:BusDefaultConcurrency set to 1. See Upgrading to parallel exchanges.
• S3-compatible storage other than AWS: AWS_REQUEST_CHECKSUM_CALCULATION and AWS_RESPONSE_CHECKSUM_VALIDATION. See Storage.
• A RabbitMQ shared with another Bitween: Bitween:QueuePrefix.
• MySQL without TLS: SslMode in the connection string. See Databases.
• The Queue health page: Bitween:RabbitMqManagementUrl, Bitween:RabbitMqManagementUsername and Bitween:RabbitMqManagementPassword.

Token:Key must be your own#

Whoever holds this key can mint a token for any identity, including one with no account behind it. The service refuses to start when it is missing, or when it is still the sample value 6547647654764764767657658658758765876532542, which ships as the chart default and is published in this repository.

The check runs in every environment, including Development, so a local checkout needs its own key too: put one in your gitignored appsettings.Development.json (or appsettings.Local.json). Any long random string will do - openssl rand -base64 48.

Changing the key invalidates every token already issued, so everyone signs in again. That is the intended response to a key you no longer trust.

Bitween:InitialAdminPassword on a new installation#

Every installation gets one administrator, [email protected], whose default password is published in this repository. On startup, while that account still has the default password:

• Bitween:InitialAdminPassword is set: it becomes the account's password. It must meet the password policy and cannot be the default itself.
• It is not set and the account is the only one: the service refuses to start. This is a new installation, and whoever signed in first could otherwise choose the password.
• It is not set and other accounts exist: nothing changes. Signing in with the default password still leads only to the password change.

Once the password is anything else the value is ignored, so it can stay in place or be removed.

Bus messages from other applications#

A message another application publishes to Bitween's bus can carry its user's token. Bitween checks it with its own Token values, so a publisher signing with a different key fails every message it sends: it goes straight to the queue's .bad queue and no exchange is created. Give both applications the same Token values. Until they match, Bus:OnInvalidUserToken (env: Bus__OnInvalidUserToken) can change what happens:

Bitween section#

Theme section#

LoginLogo, BitweenLogo, BitweenText, LinkedinLink, GithubLink, BitweenHeaderIcon, WebsiteLink, CompanyName, AllRightsReserved, CopyRightsIcon, TabTitle, TabIcon, PrimaryColor and ShowFooter. All of them are runtime settings, so configuration only supplies their first values. BitweenIcon still binds but no longer has any effect.

Storage#

Storage credentials live in the CloudFiles section and are read by the SimplyWorks.CloudFiles packages.

For an S3-compatible store other than AWS, set AWS_REQUEST_CHECKSUM_CALCULATION and AWS_RESPONSE_CHECKSUM_VALIDATION to when_required. The AWS SDK otherwise uploads with a trailing checksum, which some of these stores save into the file itself.

Azure keeps deletion rules in the storage account's lifecycle management policy, which is reached through Azure Resource Manager rather than the blob endpoint. With SubscriptionId and ResourceGroupName set, the storage library creates the temp-prefix rules at startup and the Settings page reads them. The managed identity, or a service principal in AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET, needs Microsoft.Storage/storageAccounts/managementPolicies/read and write, for example through the Storage Account Contributor role. Without them the rules aren't created on Azure, and any policy set up by hand can't be read.

Logging#

Logging lives in the SwLogger section.

Runtime settings#

Settings are stored in the Settings table and edited on the Settings page.

• On first boot, every editable setting is copied from configuration into the table. After that the table wins, and changing configuration has no effect: each start logs a warning naming every setting whose configured value differs from the stored one.
• A saved change applies immediately on the instance that saved it, and reaches other instances through the cache revoke broadcast.
• Reset to default writes the product default, not the configured value.
• Values captured at startup, such as the bus, storage, CORS and database settings, are shown read-only. Credentials only show whether they are set.

The retry poll and retention crons are validated before they're saved, and saving one reschedules its job. A document prefix must be folder names of letters, digits, dots, dashes and underscores, and no folder can be only dots (. or ..). Each exchange keeps the prefix its files were written under, so changing it only affects new exchanges.

Mail server#

The Mail server section is the one SMTP server every Email notification channel sends through, so a channel only names its recipients. Member invites, password resets and account notices go through it too; see Invites and password resets. It is read on each send. Until a host and a From address are set, Email channels can't send, and their page says so. The connection follows the SMTP adapter's rules: a password is only sent over TLS, CertificateThumbprint trusts exactly that certificate, and a server that doesn't answer within 30 seconds fails the send. The password is a secret setting, so storing it needs Bitween:SettingsEncryptionKey. Without one, set it through configuration (Bitween__MailServer__Password).

AI#

The AI section is the provider every AI feature calls; they are Generate with AI in the mapping editor, Explain this failure on a failed exchange, Ask on the Exchanges page, and Suggest with AI beside a subscription's retry policy. It is read on each call, and AI features stay off until an API key is set.

• Provider is Anthropic or OpenAI. Any other value, such as a misspelling in configuration, leaves AI features off. OpenAI also covers anything that speaks its chat completions API at API address: an Azure OpenAI resource (https://your-resource.openai.azure.com/openai/v1/), a local Ollama (http://localhost:11434/v1/) or a proxy.
• Model empty uses claude-opus-5-5 with Anthropic. OpenAI needs one named, or the Azure deployment's name.
• API key is a secret setting, so storing it needs Bitween:SettingsEncryptionKey.
• API address must be https, except plain http to this machine (localhost), so the key is never sent in the clear. Calls go through the same address check as adapters: never to link-local or cloud metadata addresses, and not to private or loopback ones while Bitween:BlockPrivateNetworkAddresses is on.

When the provider refuses or fails a call, the message gives its HTTP status, not the text it sent back.

Sample documents an AI feature sends go to this provider, with the names - never the values - of partner properties and global values. Secret ones are not named.

Explaining a failure

Explain this failure on a failed exchange sends this, and only this, to the provider:

• the error, which step failed, the subscription's kind and adapters, and the names of the handler's settings, never their values (they hold partner and global values already filled in, some of them credentials);
• the retry policy's groups, the attempt's place in its retry chain, why it won't be retried and any scheduled retry, and the first line of up to three earlier attempts' errors;
• the input, mapped and response documents, with every value replaced by its type: "name": "Lina" goes as "name": "<text>". Long lists show their first three entries. A CSV's every row is masked, a header row included, so a file without one can't send its first record as column names. A document that isn't JSON, XML or CSV, or is over 1 MB, isn't sent at all.

Error text is masked too: a document inside it, such as a partner's response body, is masked as a document; every value the exchange's documents hold is taken out wherever it appears; quoted text, numbers of four or more digits, email addresses, URL query strings and anything that looks like a credential or token are replaced; and a stack frame keeps its file name and line but not the server's folders.

The answer says what happened, the most likely cause and what to change. See what was sent shows exactly the masked message that went, after fixed instructions that are the same on every call. Anyone who can view the exchange can ask, and each request is recorded as an explain-failure operator action in the audit trail before anything is sent, so a call that fails afterwards is on record too.

Asking your exchanges

Ask on the Exchanges page turns a question such as "failed SkyNet orders since Monday" into the page's own filter: its chips, its link, its saved views. The answer line above the list counts the result itself. It sends the provider only:

• the question, the current time and the asker's time zone;
• the ids and names of partners, subscriptions and information types (up to 2,000 of each), and promoted-property keys.

No exchange, count or property value is sent. Every id and key in the answer is checked against this Bitween before it becomes a filter; anything that doesn't exist is dropped and listed under the answer. See what was sent shows exactly the message that went, after fixed instructions that are the same on every call, and each question is recorded in the audit log as ask-exchanges before it is sent. It needs exchanges.view, and the filter runs with the asker's rights like any other.

The page also has a Notification channels section. Channels are records rather than settings: they have their own table, each opens on a page of its own, and the notifiers permissions cover them rather than settings. See Notification channels.

GET /api/retention and POST /api/retention/preview describe what the retention settings do, as saved or as proposed. The Settings page uses them. POST /api/retention/aggregation says whether exchanges would be removed before an aggregation on the given schedules rolls them up; the aggregation page uses it.

GET /api/settings/config needs no sign-in. It returns the Microsoft sign-in values, whether email and password sign-in is disabled, whether RabbitMQ management is configured, whether AI features are configured (aiConfigured), and the theme. The sign-in page loads it.

Helm values#

The chart in charts/default maps values to environment variables. Values marked secret are delivered through a Kubernetes Secret.

The chart also sets SwLogger__ApplicationName to the release name and BitweenClient__BaseUrl to the in-cluster service address.

The chart's default global.token.key is a fixed value committed to the repository. Always override it.