Security
Handling your client's credential safely, and what a revocation means.
Handling Your Credential
The credential you receive from the token exchange is the one thing that proves your client's identity to Mandala from that point on. Treat it like any other long-lived secret:
- Store it once, securely, on the machine that will use it -- a secrets manager or an OS-level credential store if you have one available; at minimum, a file with restrictive permissions, never committed to source control or logged.
- Never send it over the realtime connection. The protocol already keeps it off the wire for you -- it's only ever presented to the
connect-tokenHTTPS endpoint, which trades it for the short-lived token that actually authenticates the socket connection (see Client Protocol). - Run exactly one client process per credential at a time. This isn't just tidiness -- see below for what happens if you don't.
Why a Duplicate Connection Gets the Whole Credential Revoked
Most systems that see a second connection attempt on an already-active credential simply reject the newcomer and leave the original connection alone. Karma RPA does something more aggressive on purpose: when Mandala sees a second live connection on a credential that already has one active, it treats that as evidence the credential itself may have leaked onto a second machine -- and revokes the entire credential, closing the original connection too, not just refusing the new one.
This is the same response OAuth refresh-token reuse detection uses when a token that should only ever be used once is presented a second time: if reuse is even possible, the safer assumption is compromise, not a benign race. A Karma RPA credential is long-lived and lives on a machine outside Mandala's own control -- closer to a login session than a one-time password -- so simply rejecting the duplicate would let a genuinely stolen credential keep working indefinitely, for as long as it happened not to collide with the legitimate connection.
Mandala does distinguish an ordinary reconnect (the same client dropping and reconnecting quickly) from a likely clone (a second connection while the first still looks recently active) -- see the heartbeat cadence guidance in Client Protocol. Reconnecting promptly after a drop, rather than leaving a stale connection to time out on its own before you reconnect, keeps you on the benign side of that distinction.
What You'll See If It Happens
A connection attempt on a revoked or already-claimed credential fails at the handshake, with an error to that effect (for example, indicating the credential was revoked because a concurrent connection was detected, or that the client isn't currently in a connectable state). If your client was the one still connected when the clone was detected, your existing connection is force-closed as well.
If this happens to you, it's one of two things:
- A genuine security issue -- the credential leaked to, or was reused on, a second machine. Treat this as an incident: investigate how the credential ended up in two places before reusing it anywhere.
- An operational accident -- the same client program was started twice (e.g. a supervisor/process manager restarted it while the old process hadn't fully exited), or it reconnected long enough after a network blip that Mandala could no longer tell the two connections apart as the same client.
Either way, the recovery is the same: register the client again to receive a fresh credential, update whatever secure storage your client reads it from, and make sure your deployment can't end up running two instances against one credential at once.