deepread-agent-setup

Original source / Raw SKILL.md

---
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-API-Key: $DEEPREAD_API_KEY" \
  -F "[email protected]"
```

A successful response returns a job ID confirming the key works:
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "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**: [email protected]


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "deepread001",
  "slug": "deepread-agent-setup",
  "displayName": "DeepRead Agent Self Sign Up",
  "latest": {
    "version": "2.0.4",
    "publishedAt": 1772125932525,
    "commit": "https://github.com/openclaw/skills/commit/a652d1bd438d4702486cd5871b13c3666987d9d6"
  },
  "history": [
    {
      "version": "1.0.5",
      "publishedAt": 1771501552547,
      "commit": "https://github.com/openclaw/skills/commit/99c46121592995a2709b448e9e38a1bc0898f0fd"
    }
  ]
}

```