Handling tokens and key material safely

Handling credentials, tokens, and exported key material without creating a bad day.

This service holds key material. A few habits keep an integration from becoming the weak link.

Never commit these

.env.local and any environment file carrying real values
config/tenants.json — API keys and secret hashes
Workspace directories and service state
Tokens, workspace passwords, account passwords
Exported key material, including sealed blobs

Credentials

Tenant credentials (X-Api-Key + X-Api-Secret) administer every workspace you own and mint tokens for all of them. They belong on a server you control — never in a browser, mobile app, or anything shipped to a user.

Workspace passwords are unrecoverable. The service cannot reset one or recover a workspace without it. Store them the way you store root credentials.

Workspace tokens are bearer credentials: whoever holds one has the scopes it carries until it expires or is revoked. Treat a token like a password for its whole lifetime.

Ask for the narrowest scope

Scopes are fixed at mint time but cheap to re-mint. A service that only reads and signs should hold ["read","sign"], so a leaked token cannot create or delete anything.

export is never granted by default. Request it only for the specific operation that needs it, and revoke the token immediately after.

Deletion is real

Deleting a workspace or an account destroys the key material inside it. There is no undo and no recovery from the service side.

?force=true on workspace deletion also revokes live sessions. Use it only when that is what you intend — see Manage workspaces.

Sealed exports are still key material

A sealed blob is your key, encrypted to a key your operator holds. That makes it safe from a thief who lacks the private half — and nothing else. Keep it out of logs, issue trackers, chat, and CI artifacts. Give it no longer a retention than you would give the key itself.

Check recipientFingerprint before decrypting: it identifies which key the blob was sealed to.

Handling errors safely

Branch on error.code, never on message.
Do not log whole request bodies from account creation, unlock, or token mint — they carry passwords and secrets.
Keep requestId for support. It is safe to share; the rest of the error may not be.

Transactions

Treat status: "unknown" and tx_timeout as unestablished, never as failure. Check status before resending — see Send transactions.
Simulate before sending anything consequential.
If you send from the same address by other means, manage nonce yourself.

Operational hygiene

Run one service instance per state directory. A second instance on the same storage is refused, deliberately, to protect wallet and quota records.
Keep RPC endpoint credentials in operator configuration, not client code.
Rotate tenant credentials through your operator rather than sharing them across environments.