DeepRead Agent Self Sign Up

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 rec...

Security Scan

The skill is internally coherent: it implements an OAuth device flow against api.deepread.tech, produces a DEEPREAD_API_KEY, and does not request unrelated credentials or perform unexpected actions (minor note about an undeclared dependency).

Purpose & Capability

Name/description match the included code and instructions: both Python and shell implementations perform the OAuth 2.0 device flow against api.deepread.tech and return an api_key. One minor mismatch: the shell examples/scripts require curl and jq but the skill's declared required binaries list is empty.

Instruction Scope

SKILL.md and the code instruct only calls to api.deepread.tech endpoints and local environment variable setting. The instructions do not request or read unrelated system files, secrets, or external endpoints.

Install Mechanism

No install spec is present (instruction-only). Two helper scripts are included but nothing is downloaded from arbitrary URLs and no archive extraction occurs.

Credentials

The skill requests no credentials and only produces a single environment variable (DEEPREAD_API_KEY) as expected for its purpose. There are no extra or unrelated env vars or config paths requested.

Persistence & Privilege

always is false and model invocation is disabled (disable-model-invocation: true). The skill does not attempt to persist keys automatically or modify other skills or global agent settings.

Assessment

This skill appears to do exactly what it says: run the OAuth device flow against api.deepread.tech and set DEEPREAD_API_KEY for the current session. Before installing: ensure you trust the deepread.tech domain and want to grant it an API key; note the shell script requires curl and jq (not declared), and the Python script sets the env var only inside its process (to get an exported variable in your interactive shell, source the shell script). The code does not exfiltrate data to other endpoints and does not request unrelated credentials, but treat the returned sk_live_* key as sensitive and store it in a secrets manager if you persist it.

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.

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

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:

{
  "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:

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):

{
  "error": "authorization_pending",
  "api_key": null,
  "key_prefix": null
}

After user approves:

{
  "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:

{
  "error": "access_denied",
  "api_key": null,
  "key_prefix": null
}

If code expired (15 minutes):

{
  "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:

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:

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

A successful response returns a job ID confirming the key works:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

If the key is invalid you will get a 401 Unauthorized response.

Complete Flow (All Steps)

#!/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:

export DEEPREAD_API_KEY="sk_live_your_key_here"

Security Notes

• The device flow follows RFC 8628
• 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: [e-mail]

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