Bring Your Own AI Key (BYOK)
How to configure your own AI provider keys (BYOK) in MarkDocket, including what is supported, what is explicitly excluded, and how keys are stored and used securely.
Bring Your Own Key (BYOK) lets you supply an AI provider API key from your own account and route your automation agent nodes through it, instead of using the MarkDocket platform's shared AI gateway.
Automation agent nodes only
BYOK applies exclusively to agent nodes inside Automation Runs. Interactive agent chat, trademark/patent draft research workflows, and all other AI-powered features continue to use the MarkDocket platform AI gateway and are not affected by BYOK configuration.
What BYOK does
By default, every AI call MarkDocket makes on your behalf goes through the platform's shared AI gateway. With BYOK enabled:
- Automation agent-node generation is sent from the agent to an authenticated API-owned proxy. The API resolves and decrypts your workspace-owner credential for that request, then calls the stateless BYOK provider worker instead of the shared gateway.
- API costs for those calls are billed directly to your provider account, not through MarkDocket's metered AI usage.
- You choose which provider and model your automation agent uses.
BYOK has no effect on interactive agent sessions, draft research jobs, due-diligence workflows, or any other part of the platform.
Configuring your provider key
- Open Settings → AI Provider Credentials in the MarkDocket dashboard.
- Select your AI provider from the list of supported providers.
- Paste your API key into the field and save.
Your key is encrypted at rest and bound to your account identity using authenticated encryption. The encryption includes additional authenticated data tied to your account, so the stored ciphertext cannot be decrypted or replayed in the context of a different account.
Once saved, you can update or remove your key from the same settings panel at any time. Removing a key immediately revokes BYOK generation. An agent node still configured for BYOK then fails closed; it never silently reverts to the platform gateway.
Supported and unsupported contexts
| Context | Uses BYOK? |
|---|---|
| Agent nodes in Automation Runs | Yes |
| Interactive agent chat | No |
| Trademark / patent draft research | No |
| Due-diligence workflows | No |
| Prior-art search | No |
| All other platform features | No |
How keys are protected
- Encrypted storage. Provider keys are stored encrypted in MarkDocket's database. The encryption is identity-bound so that a key stored for your account cannot be used as if it belonged to another account.
- Execution isolation. During an automation run, your key is decrypted only inside
markdocket-apifor one generation request. It is never returned to, or accessible by, the agent worker. - No credential sharing. The API resolves the active workspace owner's provider record and binds decryption to that owner/provider. The stateless BYOK worker receives the key only for the authenticated provider call and does not retain account state.
- Audit trail. Automation runs using BYOK are recorded in your run history the same way as standard runs, with per-node step outcomes visible in the automation canvas.
Billing when BYOK is active
When an automation run uses your BYOK key:
- AI token costs go to your provider account, not to your MarkDocket metered usage.
- MarkDocket still bills for product usage (automation executions, tool calls, and other platform resources) at your normal rate.
- No provider cost lines are recorded in your MarkDocket billing dashboard for BYOK-powered runs — only platform usage is tracked there.
If you remove your key or it becomes invalid, affected automation runs surface a credential/provider error and fail that node after the workflow's configured retries, rather than silently falling back to the platform gateway. You can inspect the run trace in the automation canvas to see which node encountered the issue.
Automation runs and BYOK routing
Automation runs execute as durable, checkpointed workflows. Each node runs in its own isolated step with retry and memoization. For agent nodes specifically:
- A fresh delegated authorization token is minted for each execution of an agent node.
- Provider quota, access, or credential errors remain opaque at the service boundary and fail closed. Resolve the issue with your provider or replace the saved key, then retry the run.
- Per-user concurrency is capped at two simultaneous automation runs, regardless of whether BYOK or the platform gateway is in use.
Troubleshooting
The automation run failed with a credential error. Verify that the API key saved in Settings → AI Provider Credentials is valid and has not been revoked or rate-limited on your provider account. Update the key and retry the run.
I expected BYOK to apply to my agent chat session, but it did not. BYOK is scoped exclusively to agent nodes inside Automation Runs. Interactive chat always uses the platform gateway. This is by design and cannot be changed.
Why did the run fail instead of using the platform model? BYOK selection is explicit. Falling back would charge a different credential and change the requested trust boundary, so MarkDocket requires you to fix the provider key or explicitly change the node to managed execution.
I removed my BYOK key. What happens to existing runs? Runs that are already in progress fail at the next agent node that attempts to use the BYOK path. Future runs with that node still configured for BYOK also fail closed until you save a replacement key or explicitly change the node to managed execution.
Building Automation Workflows
How to design automation workflows in the MarkDocket canvas UI — adding and connecting nodes, using template variable bindings, and overlaying historical run traces on the graph.
Automation Billing and Metering
How automation runs meter usage, what happens when a billing block signal suspends a run, and how Bring Your Own Key (BYOK) affects cost attribution during automation execution.