Keys, credits, and private AI docs in one dashboard.

Topology

Keep the dashboard and API on separate hosts for security and CORS control.

Env config

NEXT_PUBLIC_PLATFORM_URL=<your-platform-url>
NEXT_PUBLIC_API_BASE_URL=https://api.pryv.ai

Environments

Personas

Jobs to be done

• Purchase credits -> create key -> call /v1/chat/completions -> ship.
• Rotate keys, restrict usage, respond to insufficient credits.
• Inspect usage, balances, and request_id for debugging.

Platform IA

Roles are single-owner today. The wallet signing management requests is treated as the owner.

Auth model

Wallet signature payload

const message = buildWalletAuthMessage({ action: 'create' })
const { walletAddress, signature } = await signWalletMessage(message)

const body = {
  walletAddress,
  message,
  signature,
  name: 'Production key'
}

Key concepts

Typed fetch helper

export type ApiError = {
  error: { message: string; type?: string; code?: string; details?: unknown }
}

export async function fetchJson<T>(
  baseUrl: string,
  path: string,
  init?: RequestInit
): Promise<T> {
  const res = await fetch(`${baseUrl}${path}`, {
    ...init,
    headers: {
      'Content-Type': 'application/json',
      ...(init?.headers || {})
    }
  })

  const text = await res.text()
  const body = text ? (JSON.parse(text) as unknown) : null

  if (!res.ok) {
    const apiErr = body as ApiError | null
    const msg = apiErr?.error?.message || `Request failed: ${res.status}`
    const err = new Error(msg)
    ;(err as any).status = res.status
    ;(err as any).code = apiErr?.error?.code
    ;(err as any).details = apiErr?.error?.details
    throw err
  }

  return body as T
}

Wallet signing helper

import { BrowserProvider } from 'ethers'

export async function signWalletMessage(message: string) {
  const provider = new BrowserProvider((window as any).ethereum)
  const signer = await provider.getSigner()
  const walletAddress = await signer.getAddress()
  const signature = await signer.signMessage(message)
  return { walletAddress, signature }
}

export function buildWalletAuthMessage(params: {
  action: 'create' | 'list' | 'revoke' | 'checkout' | 'balance' | 'ledger'
  keyId?: string
}) {
  const nonce = crypto.randomUUID()
  const ts = new Date().toISOString()
  const keyId = params.keyId ?? ''
  return `Pryv API key mgmt | action=${params.action} | keyId=${keyId} | nonce=${nonce} | ts=${ts}`
}

POST /v1/pii/preview

export async function piiPreview(
  apiBaseUrl: string,
  apiKey: string,
  req: any
) {
  return fetchJson(apiBaseUrl, '/v1/pii/preview', {
    method: 'POST',
    headers: { Authorization: `Bearer ${apiKey}` },
    body: JSON.stringify(req)
  })
}

Models

GET /v1/models returns the models available to your API key. Cache for hours.

Use GET /v1/models/{id} for a single model details response.

List models

curl https://api.pryv.ai/v1/models \
  -H "Authorization: Bearer pryv_..."

Pricing and credits

Debits are based on model prices (USD per 1M tokens) with a margin multiplier. Preview charges $0.05 per call.

Security

• API key is shown once and cannot be recovered.
• Never commit keys; avoid localStorage by default.
• Frontend never asserts entitlement; backend is source of truth.
• Prefer POST for wallet-auth to reduce URL leakage in logs.

Operations

Caching

• Cache GET /v1/models for hours.
• Cache keys and balance for 5 to 15 seconds with manual refresh.

Retries

• Retry idempotent GETs with exponential backoff.
• Do not auto-retry key creation or checkout creation without user action.

Telemetry events

• api_keys_viewed
• api_key_created
• api_key_revoked
• billing_checkout_started
• billing_checkout_completed
• credits_balance_viewed
• insufficient_credits_error_shown
• rate_limit_error_shown