DeepRead BYOK

Bring Your Own Key to DeepRead. Connect your OpenAI, Google, or OpenRouter API key — all document processing routes through YOUR account at zero DeepRead LLM...

Security Scan

The skill's purpose (helping users enable BYOK on DeepRead) is plausible, but the instructions contain several inconsistencies and minor scope-creep (notably around file modifications and required tools) and some product claims that you should verify before trusting your keys to the service.

Purpose & Capability

The skill claims to guide BYOK setup for DeepRead and only declares DEEPREAD_API_KEY as a required credential — that matches the stated purpose. However, the SKILL.md describes adding OpenAI/Google/OpenRouter keys to DeepRead's dashboard (which is consistent) but the manifest declares no required binaries while the runtime instructions rely on curl, python3, grep/cut, and the system 'open' command. Declaring 'no required binaries' is inconsistent with the actual instructions.

Instruction Scope

The instructions include runnable shell code that: performs a device-flow against api.deepread.tech, polls for an API key, and appends DEEPREAD_API_KEY to a local .env file. Yet the document states 'No system files are modified' while the example explicitly writes to .env — that is an internal contradiction. The instructions also tell the user to paste provider keys into DeepRead’s dashboard (which is normal for BYOK) and claim provider-side validation/encryption but provide no evidence or verification steps. Overall the instructions touch secrets and local files and assume several local utilities without declaring them.

Install Mechanism

No install spec and no code files — this is instruction-only, which is the lowest install risk. Nothing will be downloaded or written by an installer beyond what the user or agent runs from the instructions.

Credentials

Only DEEPREAD_API_KEY is requested in the manifest, which is proportional for a guide that helps configure DeepRead. However, the provided script writes the key into a local .env file and later reads it with shell tools; storing secrets in a plaintext .env may expose them to other local processes or accidental commits. The skill does not request the provider keys themselves as environment variables (since it expects them to be entered in DeepRead's dashboard), which is reasonable, but the guidance asks the user to paste sensitive provider keys into a third-party dashboard — you should confirm DeepRead's security/enccryption policies independently.

Persistence & Privilege

The skill is not marked always:true and does not request elevated or cross-skill configuration changes. Autonomous invocation is allowed (platform default) but that is not, on its own, a new concern here.

What to consider before installing

This skill mostly does what it says (walk you through enabling BYOK on DeepRead), but be cautious before proceeding: 1) The SKILL.md's example scripts assume curl, python3, grep/cut and an 'open' command — make sure those utilities are available and understand what the script will write (it appends your DeepRead key to a local .env file). 2) The doc contradicts itself: it claims 'No system files are modified' yet writes to .env—expect local file modification. 3) The claim that 'page quota is skipped entirely' and that provider keys are 'validated' and 'encrypted at rest' are product claims you should verify with DeepRead (check their docs or support). 4) If you add provider keys to DeepRead, consider using keys with limited scope/quota, enable billing alerts, and avoid pasting long-lived production keys if you can use scoped/test keys first. 5) If you do not fully trust deepread.tech, do not paste your provider keys into the dashboard. If you want this skill to be less risky, ask for explicit verification steps (where the key is stored, encryption details) and for the manifest to declare the actual required local tools.

DeepRead BYOK — Bring Your Own AI Key

Use your own OpenAI, Google, or OpenRouter API key for all DeepRead document processing. Your key, your billing, zero DeepRead LLM costs.

Without BYOK:  You → DeepRead API → DeepRead pays OpenRouter → You pay DeepRead
With BYOK:     You → DeepRead API → YOUR key pays provider   → DeepRead cost = $0

Page quota is skipped entirely for BYOK users. Process unlimited pages on any plan.

This skill helps agents guide users through BYOK setup on DeepRead. The agent opens the dashboard for key management and uses https://api.deepread.tech for document processing. No system files are modified.

What Changes With BYOK

• LLM costs: You pay your provider directly instead of DeepRead
• Page quota: Skipped entirely — no monthly limit when using your own key
• API calls: Same endpoints, same headers — zero code changes
• Processing quality: Equivalent models from your provider via tier-based swapping
• Setup: One-time — add your provider key in the dashboard, then forget about it

Supported Providers

• OpenRouter (sk-or-...) — Easiest setup. Same models DeepRead uses, just swaps billing to your account.
• OpenAI (sk-proj-...) — Direct to api.openai.com. Best for enterprise agreements and negotiated rates.
• Google (AI...) — Direct to Google AI API. Best for Google Cloud credits and existing billing.

Setup Guide

Step 1: Get Your DeepRead API Key

If you don't have one yet, use the device flow:

DR_RESPONSE=$(curl -s -X POST https://api.deepread.tech/v1/agent/device/code \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"Claude Code"}')

DR_DEVICE_CODE=$(echo "$DR_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['device_code'])")
DR_VERIFY_URL=$(echo "$DR_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['verification_uri_complete'])")

echo "Open this URL to approve: $DR_VERIFY_URL"
open "$DR_VERIFY_URL" 2>/dev/null

while true; do
  sleep 5
  DR_TOKEN_RESP=$(curl -s -X POST https://api.deepread.tech/v1/agent/device/token \
    -H "Content-Type: application/json" \
    -d "{\"device_code\":\"$DR_DEVICE_CODE\"}")
  DR_API_KEY=$(echo "$DR_TOKEN_RESP" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('api_key',''))" 2>/dev/null)
  if [ -n "$DR_API_KEY" ] && [ "$DR_API_KEY" != "" ]; then
    echo "Got API key: ${DR_API_KEY:0:12}..."
    printf "\nDEEPREAD_API_KEY=%s\n" "$DR_API_KEY" >> .env
    break
  fi
done

Or sign up directly: https://www.deepread.tech/dashboard/?utm_source=clawhub

Step 2: Add Your Provider Key in the Dashboard

BYOK keys are managed through the DeepRead dashboard:

open "https://www.deepread.tech/dashboard/byok?utm_source=clawhub"

In the dashboard:

1. Click Add Provider Key
2. Select your provider — OpenRouter, OpenAI, or Google
3. Paste your API key
4. The key is validated against the provider's API before saving
5. The key is encrypted at rest and stored securely

That's it. All subsequent API calls automatically route through your key.

Step 3: Process Documents (Same API as Before)

Nothing changes in your code. Same endpoints, same X-API-Key header:

DR_API_KEY=$(grep ^DEEPREAD_API_KEY .env | cut -d= -f2)

curl -X POST https://api.deepread.tech/v1/process \
  -H "X-API-Key: $DR_API_KEY" \
  -F "file=@document.pdf"

Under the hood, LLM calls now route through YOUR provider key. Page quota is NOT counted.

Managing Your Key

All key management is done in the dashboard at https://www.deepread.tech/dashboard/byok

• Toggle on/off: Switch between your key and DeepRead processing without deleting the key
• Replace: Add a new key to replace the existing one (one active key at a time)
• Delete: Permanently removes the key, reverts to DeepRead processing

How Model Swapping Works

When you provide an OpenAI or Google key, DeepRead automatically swaps all pipeline models to equivalents from your provider at the same quality tier:

Top tier — GPT-5 (OpenAI) or Gemini 2.5 Flash (Google)

High tier — GPT-5 Mini (OpenAI) or Gemini 2.5 Flash (Google)

Mid tier — GPT-5 Nano (OpenAI) or Gemini 3 Flash (Google)

Lite tier — GPT-5 Nano (OpenAI) or Gemini 2.5 Flash Lite (Google)

OpenRouter users: No swapping needed — same models, your billing account.

Python Example

import requests
import time

# Once BYOK is enabled in the dashboard, your existing code just works.
# LLM costs go to YOUR provider account. Page quota is not counted.

API_KEY = "sk_live_YOUR_KEY"
BASE = "https://api.deepread.tech"
headers = {"X-API-Key": API_KEY}

# Submit document — same API call as always
with open("invoice.pdf", "rb") as f:
    job = requests.post(
        f"{BASE}/v1/process",
        headers=headers,
        files={"file": f},
        data={"schema": '{"type":"object","properties":{"vendor":{"type":"string"},"total":{"type":"number"}}}'}
    ).json()

job_id = job["id"]
print(f"Job {job_id} — LLM costs go to your provider account")

# Poll for results
delay = 3
while True:
    time.sleep(delay)
    result = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=headers).json()
    if result["status"] == "completed":
        print(f"Extracted: {result['structured_data']}")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result['error']}")
        break
    delay = min(delay * 1.5, 15)

JavaScript Example

// Once BYOK is enabled in the dashboard, your existing code just works.

const API_KEY = "sk_live_YOUR_KEY";
const BASE = "https://api.deepread.tech";

const form = new FormData();
form.append("file", fs.createReadStream("invoice.pdf"));

const { id: jobId } = await fetch(`${BASE}/v1/process`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY },
  body: form,
}).then(r => r.json());

console.log(`Job ${jobId} — LLM costs go to your provider account`);

let delay = 3000;
let result;
do {
  await new Promise(r => setTimeout(r, delay));
  result = await fetch(`${BASE}/v1/jobs/${jobId}`, {
    headers: { "X-API-Key": API_KEY },
  }).then(r => r.json());
  delay = Math.min(delay * 1.5, 15000);
} while (!["completed", "failed"].includes(result.status));

Security

• Encrypted at rest — Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256)
• Validated before storing — test API call to your provider confirms the key works
• Key hints only — dashboard shows only the last 4 characters for identification
• Separate encryption key — encryption key stored separately from the database
• Soft-delete — removing a key clears the ciphertext from the database
• One key at a time — simple billing, all processing routes through one provider

When to Use BYOK

Use BYOK if:

• You have an OpenAI enterprise agreement with negotiated rates
• You have Google Cloud credits you want to apply to document processing
• You want zero DeepRead LLM costs and unlimited page processing
• You need all AI calls to go through your own provider account for compliance
• You're on the free tier and want to skip the 2,000 page/month limit

Don't use BYOK if:

• You're happy with DeepRead's default processing — it works great out of the box
• You don't have an existing AI provider account
• You want DeepRead to handle all billing in one invoice

Works With All DeepRead Skills

BYOK applies to every DeepRead API call — OCR, form fill, and PII redaction:

• deepread-ocr — Extract text and structured JSON from documents — clawhub install uday390/deepread-ocr
• deepread-form-fill — Fill any PDF form with AI vision — clawhub install uday390/deepread-form-fill
• deepread-pii — Redact sensitive data from documents — clawhub install uday390/deepread-pii
• deepread-agent-setup — Authenticate via OAuth device flow — clawhub install uday390/deepread-agent-setup
• deepread-byok — Set up Bring Your Own Key (this skill) — clawhub install uday390/deepread-byok

Support

• Dashboard: https://www.deepread.tech/dashboard
• BYOK Settings: https://www.deepread.tech/dashboard/byok
• Issues: https://github.com/deepread-tech/deep-read-service/issues
• Email: [e-mail]

---

Ready? Add your provider key at https://www.deepread.tech/dashboard/byok