Skill: uday390/deepread-agent-setup (version 2.1.0)

--- name: deepread-agent-setup title: DeepRead Agent Setup description: Authenticate AI agents with the DeepRead OCR API using OAuth device flow. The agent displays a code, the user approves it in their browser, and the agent receives a DEEPREAD_API_KEY stored as an environment variable. disable-model-invocation: true metadata: {"openclaw":{"produces":{"env":["DEEPREAD_API_KEY"]},"homepage":"https://www.deepread.tech"}} --- # DeepRead Agent Setup Authenticate AI agents with the DeepRead OCR API using the **OAuth 2.0 Device Authorization Flow** (RFC 8628). After setup, the agent has a `DEEPREAD_API_KEY` environment variable and can use the [DeepRead OCR skill](https://clawhub.ai/deepread-tech/deepread). ## How It Works The device flow lets headless agents (no browser) authenticate securely: ``` Agent requests device code → User opens URL in browser → User approves → Agent receives API key ``` 1. Agent calls `POST https://api.deepread.tech/v1/agent/device/code` to get a `device_code` and `user_code` 2. Agent displays the `user_code` and a verification URL to the user 3. User opens the URL in their browser, logs in, and enters the code 4. Agent polls `POST https://api.deepread.tech/v1/agent/device/token` until the user approves 5. Agent receives an `api_key` (prefixed `sk_live_`) and stores it as the `DEEPREAD_API_KEY` environment variable **Only domain contacted:** `api.deepread.tech` ## Prerequisites - A DeepRead account (free at https://www.deepread.tech/dashboard/?utm_source=clawdhub) - Internet access to reach `api.deepread.tech` ## Setup Instructions ### Step 1: Request a Device Code ```bash curl -s -X POST https://api.deepread.tech/v1/agent/device/code \ -H "Content-Type: application/json" \ -d '{"agent_name": "my-ai-agent"}' ``` The `agent_name` field is optional — it is shown on the approval screen so the user knows which agent is requesting access. **Response:** ```json { "device_code": "GmRhmhcxhZAzk...EeNu5OfKhL79MQgN", "user_code": "WDJB-MJHT", "verification_uri": "https://www.deepread.tech/activate", "verification_uri_complete": "https://www.deepread.tech/activate?code=WDJB-MJHT", "expires_in": 900, "interval": 5 } ``` **Tell the user** (using the values from the response — they change every time): > Open **{verification_uri}** and enter code **{user_code}** > > Or open this direct link: **{verification_uri_complete}** ### Step 2: Poll for Approval Poll every `interval` seconds (default: 5) until the user approves: ```bash curl -s -X POST https://api.deepread.tech/v1/agent/device/token \ -H "Content-Type: application/json" \ -d '{"device_code": "GmRhmhcxhZAzk...EeNu5OfKhL79MQgN"}' ``` **While waiting (user hasn't approved yet):** ```json { "error": "authorization_pending", "api_key": null, "key_prefix": null } ``` **After user approves:** ```json { "error": null, "api_key": "sk_live_abc123def456...", "key_prefix": "sk_live_abc123de" } ``` **The `api_key` is returned exactly once.** The next poll after retrieval will return `expired_token`. Save it immediately. **If user denied:** ```json { "error": "access_denied", "api_key": null, "key_prefix": null } ``` **If code expired (15 minutes):** ```json { "error": "expired_token", "api_key": null, "key_prefix": null } ``` ### Step 3: Store the API Key Once you receive the `api_key`, set it for the current session: ```bash export DEEPREAD_API_KEY="<api_key from response>" ``` **To persist across sessions, the user should choose one of these options:** | Method | Command | Security | |---|---|---| | **Secrets manager (recommended)** | Use your OS keychain, 1Password CLI, or `pass` | Encrypted at rest | | **Shell profile** | User manually adds `export DEEPREAD_API_KEY="..."` to `~/.zshrc` | Plaintext file — readable by local processes | **Important:** - The agent should set the env var for the current session only (`export`) - Persistence is the **user's choice** — do not automatically write to shell profiles - Never commit the key to source control or write it to project files - The key prefix `sk_live_` confirms it is a valid DeepRead production key ### Step 4: Verify the Key Works Submit a test document to confirm the key is valid: ```bash curl -s -X POST https://api.deepread.tech/v1/process \ -H "X-[REDACTED_SECRET]" \ -F "file=@test.pdf" ``` A successful response returns a job ID confirming the key works: ```json { "id": [REDACTED_SECRET], "status": "queued" } ``` If the key is invalid you will get a `401 Unauthorized` response. ## Complete Flow (All Steps) ```bash #!/bin/bash # DeepRead Device Flow — complete example # 1. Request device code RESPONSE=$(curl -s -X POST https://api.deepread.tech/v1/agent/device/code \ -H "Content-Type: application/json" \ -d '{"agent_name": "my-ai-agent"}') DEVICE_CODE=$(echo "$RESPONSE" | jq -r '.device_code') USER_CODE=$(echo "$RESPONSE" | jq -r '.user_code') VERIFY_URI=$(echo "$RESPONSE" | jq -r '.verification_uri') VERIFY_URI_COMPLETE=$(echo "$RESPONSE" | jq -r '.verification_uri_complete') INTERVAL=$(echo "$RESPONSE" | jq -r '.interval') echo "Open $VERIFY_URI and enter code: $USER_CODE" echo "Or open directly: $VERIFY_URI_COMPLETE" # 2. Poll for token while true; do TOKEN_RESPONSE=$(curl -s -X POST https://api.deepread.tech/v1/agent/device/token \ -H "Content-Type: application/json" \ -d "{\"device_code\": \"$DEVICE_CODE\"}") ERROR=$(echo "$TOKEN_RESPONSE" | jq -r '.error // empty') if [ -z "$ERROR" ]; then export DEEPREAD_API_KEY=$(echo "$TOKEN_RESPONSE" | jq -r '.api_key') echo "Authenticated. DEEPREAD_API_KEY is set for this session." break elif [ "$ERROR" = "authorization_pending" ]; then sleep "$INTERVAL" elif [ "$ERROR" = "slow_down" ]; then INTERVAL=$((INTERVAL + 5)) sleep "$INTERVAL" else echo "Error: $ERROR" exit 1 fi done ``` ## Endpoints Used | Endpoint | Method | Auth | Purpose | |---|---|---|---| | `https://api.deepread.tech/v1/agent/device/code` | POST | None | Request device code + user code | | `https://api.deepread.tech/v1/agent/device/token` | POST | None | Poll for API key after user approval | | `https://www.deepread.tech/activate` | — | Browser | User opens this URL to enter the code and approve | **No other endpoints are contacted by this skill.** ## Troubleshooting ### "authorization_pending" keeps repeating The user hasn't approved yet. Keep polling. The code expires after 15 minutes (`expires_in: 900`). ### "expired_token" The device code expired before the user approved, or the API key was already retrieved (one-time retrieval). Start over from Step 1. ### "slow_down" You're polling too fast. Increase the polling interval by 5 seconds. ### "access_denied" The user clicked Deny on the approval screen. Start over from Step 1 if the user wants to retry. ### Key doesn't work after export Ensure the shell session was not restarted. If persisting to `~/.zshrc`, run `source ~/.zshrc` to reload. ### "DEEPREAD_API_KEY not set" The environment variable was not persisted. Re-run the device flow or manually set: ```bash export DEEPREAD_API_KEY="sk_live_your_key_here" ``` ## Security Notes - The device flow follows [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628) - The `user_code` is short-lived (15 minutes) and single-use - The `api_key` is returned exactly once — subsequent polls return `expired_token` - All communication is over HTTPS - The agent sets `DEEPREAD_API_KEY` for the current session only — it does not write to disk - For long-term storage, prefer a secrets manager (OS keychain, 1Password CLI, `pass`) over plaintext shell profiles - Never commit the key to source control or write it to project files - The agent never sees the user's password ## Support - **Dashboard**: https://www.deepread.tech/dashboard - **Issues**: https://github.com/deepread-tech/deep-read-service/issues - **Email**: [REDACTED_SECRET] ## Related DeepRead Skills - **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 14 types of PII from documents — `clawhub install uday390/deepread-pii` - **deepread-agent-setup** — Authenticate via OAuth device flow (this skill) — `clawhub install uday390/deepread-agent-setup` - **deepread-byok** — Bring Your Own Key for zero LLM costs — `clawhub install uday390/deepread-byok`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)