BYOK Key Storage and Encryption

What BYOK covers

When you add an AI provider credential under Account → AI Provider Credentials, MarkDocket stores it encrypted in the platform database. That credential is then available exclusively to Agent nodes inside Automation Runs — no other execution path can access it.

Specifically, BYOK keys are never used by:

• Interactive agent chat sessions
• Draft research workflows (trademark, patent, due-diligence)
• Any direct LLM call initiated by the platform on your behalf outside of an automation

The settings UI itself displays this restriction: BYOK is limited to "Agent nodes in Automation Runs only."

Encryption at rest

BYOK keys are encrypted before being written to the database by a dedicated cryptographic module (byok-crypto) running inside the API server — the only service that writes to the database.

Identity-bound additional authenticated data (AAD)

Encryption uses identity-bound additional authenticated data. This means your user identity is cryptographically bound to the ciphertext at the time of encryption. The AAD encodes who the key belongs to, so:

• A ciphertext produced for one user identity cannot be successfully decrypted under a different user identity, even if an attacker obtained both the ciphertext and the encryption key material.
• Any tampering with the stored record that alters the identity binding causes decryption to fail outright rather than silently returning wrong plaintext.

This is an authenticated encryption scheme — the integrity of both the ciphertext and the identity claim is verified on every decryption attempt.

Storage location

Encrypted key material is stored in the Neon Postgres database. The API server (markdocket-api) is the sole writer to this database. No other service — including the agent worker — reads or writes BYOK records directly.

Execution boundary

The BYOK execution path crosses two deliberately narrow service boundaries. The flow works as follows:

1. When an automation run reaches an Agent node configured for BYOK, markdocket-agent keeps its normal AI SDK tool loop but sends each non-streaming LanguageModelV3 generation request to markdocket-api with its short-lived delegated token.
2. The API re-resolves the authenticated actor and workspace owner, validates the provider/model pair, selects the workspace-owner credential, and decrypts it inside the API process (validating owner/provider-bound AAD).
3. The API constructs billing attribution from that trusted identity and passes the decrypted key to the authenticated byok-ai-worker for that one provider call.
4. The worker returns only the non-streaming generation result. Neither API nor worker responses contain the provider key, and the agent never calls the BYOK worker directly.

This means:

• Your provider key is never held by the stateless agent worker process.
• The key is only decrypted at the moment one generation is needed, within the API server's trust boundary.
• Outside of an active automation agent node, the key exists only as ciphertext in the database.

Metering and BYOK runs

Automation nodes executing via BYOK emit product and infrastructure usage events to the MarkDocket metering system. BYOK provider-attempt/token metering is owned by byok-ai-worker and is classified as zero MarkDocket provider cost; markdocket-api does not duplicate those events. This keeps your provider charges separate from platform-managed AI spend.

Summary of protections

Configuring BYOK credentials

To add or update a provider key:

1. Open Account → AI Provider Credentials in the MarkDocket dashboard.
2. Select your AI provider and enter your API key.
3. Save. The key is encrypted and stored immediately; the plaintext is not retained in the browser or in any log.

To use BYOK in an automation, open the Automation Builder, select an Agent node, and choose your saved credential from the node configuration panel. Automation runs that do not have a BYOK credential configured continue to use the platform AI gateway.