Security and limits

Authentication

• OAuth 2.1. OSINTverse is the authorization server (https://osintverse.com/api/auth). Clients discover it through RFC 9728 protected resource metadata at /.well-known/oauth-protected-resource/mcp, use PKCE, and receive short-lived access tokens (one hour) with rotating refresh tokens (30 days). Access tokens are bound to the https://osintverse.com/mcp audience and rejected anywhere else.
• Client identity. Claude and Claude Code identify themselves with Client ID Metadata Documents; the consent screen shows the host of that document, not a self-asserted name. Clients that register dynamically are labelled Unverified app.
• API keys. An ov_ key sent as Authorization: Bearer (or x-api-key) resolves to its owner and wallet exactly as on the REST API. Suspended accounts are rejected on both paths.
• Tokens are accepted only in headers, never in the query string.

Scopes

osint:read is always granted. On the consent screen you can untick Run paid lookups or Create cases, and the agent connects without them. tools/list only advertises the tools the granted scopes allow. Calling anything else returns 403 insufficient_scope so the client can ask for more.

Spend guardrails

1. Sandbox first. New connections start in sandbox mode: tools return sample data and nothing is charged. Only a person can switch a connection to live, from the dashboard; no tool can change the mode. Sandbox searches and cases expire after 7 days and are deleted by a weekly job. The query text of a sandbox search is kept only so it can be shown back to you.
2. Quote before charge. quote_search and quote_bulk_search never charge and report price, balance, and whether the caps allow the call. Paid tools are annotated as destructive so clients confirm first. On clients that support MCP confirmations, lookups over the amount you set on the consent screen also show OSINTverse's own yes/no prompt with the price. That confirmation is signed, bound to your connection and the exact call, and expires after ten minutes.
3. Two daily caps. Each workspace has a cap for all agents and API keys together (default $5 per UTC day). Each OAuth connection can also have its own cap, set on the consent screen, which counts only that agent's spend. A call must fit both. whoami shows each cap with what is spent and left, and a cap error says which one was hit. The check runs inside a database lock, so two parallel calls cannot both pass a cap with room for one.
4. Provider allowlist. Teams keep their existing allowlist and monthly cap; workspaces can also restrict which providers agents may use.
5. Rate limits. 60 tool calls and 10 paid searches per minute per connection (sandbox runs count only toward the 60). A limited tool call comes back as a rate_limited tool error with retry_after_s, so the agent can wait and retry. API keys also keep the REST limit of 1,000 requests per day.
6. Pause switch. Turn agent access off for a workspace at any time; every agent and key then gets a clear error.

Spend is reconciled against what the search API actually charged. When a search is still running as the call returns, the quoted price counts until the search finishes; the next get_search or list_searches that sees it finished corrects the amount, and a refunded search drops to $0.

What the server never does

• Delete searches or cases, share cases, or change triage.
• Top up, refund, or move credits.
• Create, list, or revoke API keys, or change team settings.
• Read another workspace. Team members only see the team wallet they chose on consent.

Provider data is untrusted

Results are returned as plain JSON with a _note that provider fields are data, not instructions. Control characters, inline images, oversized strings, and raw payloads are stripped, and pages are capped at about 60,000 characters. Query text is never written to audit rows, server logs, or analytics.

Revoking access

Dashboard → API keys → Agents lists every connected app, and every API key that called the server this month, with its cap, spend today and this month, call count, and last use. Recent agent calls below it logs each tool call with its outcome and cost (never arguments or query text); team owners and admins see every member's calls. Revoke removes the grant, refresh token, and stored settings; an access token already issued expires within the hour. Team owners and admins can detach a member's agent from the team wallet without touching the member's own grant.