TallwrightDocs

Rolling out to many end customers

A vendor whose agent serves many businesses gives each of them an Environment of their own: their own log, their own recording key, their own evidence. This page is the order to do it in. Every call here is in the SDK; what each one promises is in the API reference.

1. Keep the account key away from the agent

An Owner or Admin makes an account key (ta_…) on the backoffice's Settings screen. It makes and closes Environments, so it lives in the system that onboards your customers, never in the process that records. A recording key can do one thing: append to one Environment's log.

Removing the person who made an account key from your team revokes that key. When they leave, make the replacement and put it in place first, then remove them.

2. Make one Environment per end customer

import os
from tallwright_cloud import Account

account = Account("https://app.tallwright.com", os.environ["TALLWRIGHT_ACCOUNT_KEY"])
made = account.create("Bäckerei Müller", customer_ref="4711", deployer_label="acme-voice")
vault.write("4711", made.key.reveal())     # shown once, here and nowhere else
  • customer_ref is your own id for the customer and is required, so a repeated create makes nothing twice.
  • maybe_ours is true when an earlier attempt of the same call may have made the Environment: a create whose answer was lost tries again on its own, and the 409 that attempt meets raises EnvironmentExists with maybe_ours true. A create you issue again yourself, after an AccountError or from a restarted job, is a new call and says maybe_ours false, even when your lost first call made the Environment. Either way it is in your account under your customer_ref: account.new_key(error.environment.id) gives it a key you hold.
  • The key is shown once. Keep it in your secret store, keyed by customer_ref.

3. Record for each customer through one client

from tallwright_cloud import Environments

environments = Environments(ingest_url, key_for=lambda customer: vault.read(customer), evidence=evidence)
environments.client("4711").submit(content, action_type="callback.promised")
  • One sending thread serves every customer; each customer's evidence lives beneath its customer_ref.
  • key_for is yours: nothing on this side can tell two customers' keys apart before the door answers.

4. Keep each customer's evidence where it outlives the process

The evidence is the only copy of the content and of the salt that opens its record. Put it on a volume that outlives the container, or in a bucket (S3Evidence). The client refuses, by default, a directory on a file system that ends with its container. See evidence that outlives the process.

5. Replace a key, take exhibits, and say goodbye

  • A key that may have leaked: account.new_key(environment.id), with the Environment account.find(customer_ref) returns (its id; its environment_id is another value, which the account API does not look up), write the new key to your vault, then environments.forget(customer_ref) so the next client asks key_for again. The old key stops at once. Records pending under the old key are sent with resend(record_id, adopt=True).
  • Exhibits for a customer: an export key per Environment, made on the Environments screen, kept where the exhibits are wanted rather than where the agent runs. See the quickstart.
  • A customer who leaves: account.close(environment.id). Nothing more is recorded for them; their log stays and still exports.