# Step 1: Setup & Hello World

You are integrating **Assistiv Gateway** as the AI backend for this platform.
Assistiv is a multi-tenant API gateway that sits between your platform and
LLM providers (OpenAI, Anthropic, Google, xAI). It gives you a single
OpenAI-compatible API with built-in:

- **Multi-provider inference** — call any LLM through one endpoint, switch models without code changes
- **Per-user budgeting** — cap AI spend per end user with display-friendly units (credits, tokens, etc.), idempotent topups, manual debits for chargebacks, suspension, and a full transaction ledger
- **Rate limiting** — per-user and platform-wide RPM/TPM/RPD controls
- **Hosted MCP tools** — let the model call GitHub, Slack, Zoho, Zendesk on behalf of users via OAuth
- **Usage tracking** — per-call logs with cost, tokens, latency for billing reconciliation
- **Outbound webhooks** — real-time events on topup / debit / low-balance / suspension (HMAC-signed, retried, replayable)

## What you'll be building (integration overview)

The integration happens in steps. Each step builds on the previous one:

1. **Setup & Hello World** (this step) — Dashboard config, server-side setup, verify connection
2. **Provision End Users** — When users sign up on your platform, create them in Assistiv with a budget
3. **Budgets & Rate Limits** — Handle plan changes, upgrades, display balance
4. **Inference** — Wire up chat completions and/or the Responses API
5. **MCP Tools** (optional) — OAuth flow for third-party tools, hosted execution
6. **Monitor & Operate** — Logs, self-service endpoints, cost reconciliation

---

## Before you implement — understand the platform

**Ask the developer:** "What does your platform do, and what AI features are
you adding? Are you building a chatbot, an AI assistant, agent workflows,
or something else? This helps me understand which parts of Assistiv to
prioritize."

Understanding the product shapes the integration:
- **Chat/assistant UI** → You'll focus on Steps 2-4 (provision users, budgets, inference)
- **Agent with tool use** → You'll also need Step 5 (MCP tools + OAuth)
- **API-only (no end-user UI)** → You may skip display budgeting and self-service endpoints

---

## Prerequisites (do these on the website once)

Go to `assistiv.ai/dashboard` and:

1. **Sign up / get provisioned.** Platform signup is not self-serve via API. Assistiv provisions your tenant and shows you a `sk-plat_*` platform API key — copy and store it.
2. **Add LLM provider keys.** Paste your OpenAI / Anthropic / Google / xAI keys. Until at least one provider key is added, `/v1/chat/completions` has no upstream and returns an error.
3. **Top up your wallet via Stripe.** Inference debits USD from your platform wallet after every successful call. If the wallet is empty, inference returns `402 payment_required`.
4. **Configure end-user budgeting display.** Set your display unit ("credits", "tokens", etc.) and the credits-per-USD conversion rate. This determines what end users see when they check their balance — they never see raw USD amounts.
5. **(Optional) Set platform default rate limits.** Platform-wide RPM/TPM/RPD limits applied to every end user unless you override programmatically per-user.
6. **(Optional, for hosted MCP tools) Activate MCP apps.** For each app (GitHub, Slack, Zoho Mail, Zendesk), paste your OAuth Client ID/Secret from the provider's developer console and provide your platform's base URL (e.g. `https://my-saas.com`). Set the OAuth callback URL **at the provider** (GitHub/Slack/etc.) to `https://mcp.assistiv.ai/oauth/callback`. Activating an app unlocks two things: (a) end users on your platform can connect their personal account via OAuth, and (b) once connected, your `/v1/responses` calls can pass an MCP tool item and the model will call that user's GitHub/Slack on their behalf — see Step 5 (MCP Tools).

Come back here with your `sk-plat_*` key and your platform ID (UUID, shown on the dashboard).

---

## Set up server-side access

The Assistiv platform key (`sk-plat_*`) is a server-side-only secret — it
must never be exposed to browsers. Every step from here on (provisioning
users, setting budgets, proxying inference) requires server-side code that
can call the Assistiv API with this key.

### Find or create a server-side component

Search the codebase for where server-side logic already runs:

- **Backend framework** — Express, FastAPI, Rails, Django, etc.
- **Framework API routes** — Next.js `app/api/`, Nuxt `server/api/`,
  SvelteKit `+server.ts`, Remix loaders/actions
- **Serverless functions** — Vercel Functions, Netlify Functions,
  Cloudflare Workers, AWS Lambda
- **Database functions** — Supabase Edge Functions, Neon serverless
  drivers, Firebase Cloud Functions

**Ask the developer:** "Where does your server-side code live? I need a
place to securely call the Assistiv API with the platform key. If you
don't have a backend, what's your preferred option — Vercel/Netlify edge
functions, Supabase Edge Functions, or something else?"

Pick the option that fits the existing stack. This is where all Assistiv
API calls will live for the rest of the integration.

### Add Assistiv keys to your environment

**Server-side** (`.env`, deployment dashboard, secrets manager):

```bash
# Required — from assistiv.ai/dashboard
ASSISTIV_PLATFORM_KEY=sk-plat_...     # Server-side only — NEVER expose to browsers
ASSISTIV_PLATFORM_ID=...              # Platform UUID
ASSISTIV_API_BASE=https://api.assistiv.ai/v1  # Optional, this is the default
```

**Client-side** (if the frontend will call Assistiv directly for end-user
endpoints like `GET /v1/me/budget`):

```bash
# Use your framework's client env var prefix (REACT_APP_, NEXT_PUBLIC_, VITE_, etc.)
REACT_APP_ASSISTIV_API_BASE=https://api.assistiv.ai/v1
```

The end-user key (`sk-eu_*`) is safe to use from the browser — it's scoped
to a single user and can only access their own data. The platform key
(`sk-plat_*`) must never reach the client.

**Ask the developer:** "Where does your project store environment variables?
(.env file, Vercel dashboard, AWS Secrets Manager, etc.)"

---

## Verify the connection

### Quick check from terminal

```bash
export ASSISTIV_PLATFORM_KEY=sk-plat_...     # from the dashboard
export API=https://api.assistiv.ai/v1

# 1. List models enabled on your platform
curl -sS $API/models \
  -H "Authorization: Bearer $ASSISTIV_PLATFORM_KEY" | jq -r '.data[].id'

# 2. Pick a slug from the output above
export MODEL=provider/model-slug   # ← replace with a real slug

# 3. Smallest possible inference call
curl -sS $API/chat/completions \
  -H "Authorization: Bearer $ASSISTIV_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 32
  }' | jq
```

### Verify from the platform's server-side code

More importantly, verify the connection works from the server-side component
you identified above — not just from your terminal. Create a health-check
endpoint using whatever framework/pattern the platform already uses (API
route, serverless function, Express handler, etc.).

The endpoint should:

1. Read `ASSISTIV_PLATFORM_KEY` and `ASSISTIV_API_BASE` from the environment
2. Call `GET {ASSISTIV_API_BASE}/models` with `Authorization: Bearer {key}`
3. Return `{"status": "connected", "models": [...]}` on success
4. Return `{"status": "error", "code": <http_status>}` on failure

```
GET {ASSISTIV_API_BASE}/models
Authorization: Bearer {ASSISTIV_PLATFORM_KEY}

Success response:
  { "object": "list", "data": [{ "id": "gpt-4o", ... }, ...] }
```

Build this in the platform's own framework and routing style. Hit the
endpoint. If you get the connected response with a list of models, your
server-side setup is working and you're ready for Step 2.

### Troubleshooting

| Status | What it means | What to do |
|---|---|---|
| `401 unauthorized` | Wrong or typo'd key | Re-copy `sk-plat_*` from the dashboard; check the env var is loaded |
| `402 payment_required`, `code: wallet_insufficient` | Platform wallet empty | Dashboard → Wallet → Top up |
| `404 not_found`, `code: model_not_found` | Model slug not enabled | Use a slug from the `/models` response |
| `500 internal_error` | Likely a provider key issue | Dashboard → LLM Configs → verify a provider key is active |
| Connection refused / timeout | Env vars not reaching server-side code | Check that the env is loaded in the correct runtime (not just the build step) |

---

## Two Key Types (reference)

Every API call uses a Bearer token. There are two kinds — you'll use both
during integration:

**`sk-plat_*` — Platform key.** Server-side only. Never expose to browsers.
Used for: provisioning end users, managing budgets and rate limits, reading
logs, managing API keys.

**`sk-eu_*` — End-user key.** Scoped to one end user. Safe for frontend or
backend. Used for: inference (chat completions, responses API), model
listing, self-service endpoints (`/v1/me/*`), MCP connections and tools.

Using the wrong key type returns `403 forbidden`. Each step below notes
which key type to use.

---

Next: [Step 2 — Provision End Users](https://www.assistiv.ai/docs/integration/step-2-provision-end-users.txt)