Integration guide

Follow these steps in order. Skip optional steps unless you need them.

Checklist

Step	Action	Done when
1	Install core	`php artisan sanvex:list` runs
2	Install a driver	Driver appears in `sanvex:list`
3	Configure `.env`	Env vars set for your auth mode
4	Connect credentials	`isConfigured()` is `true`
5	Verify	API call or agent tool succeeds
6	Agents (optional)	Tools registered on Laravel AI or MCP

Step 1: Install core

Requirements: PHP 8.2+, Laravel 12 or 13, Composer.

composer require sanvex/core sanvex/cli
php artisan migrate
php artisan sanvex:list

Migrations create sv_* tables automatically. No separate Sanvex migrate command. Optional: production encryption key:

php artisan sanvex:keygen
# Add SANVEX_KEK=... to .env (otherwise APP_KEY is used)

Step 2: Install a driver

composer require sanvex/github   # API key — fastest path
# composer require sanvex/gmail   # OAuth only
# composer require sanvex/notion
# composer require sanvex/slack
# composer require sanvex/linear

php artisan sanvex:list

Your driver id (e.g. github, gmail) must appear in the table. Driver packages register with Laravel automatically after Composer install. You do not add them to config/sanvex.php unless you built a custom driver class.

Step 3: Configure `.env`

Open the driver’s Configuration page for exact variable names:

Driver	Configuration
GitHub	GitHub configuration
Gmail	Gmail configuration
Linear	Linear configuration
Notion	Notion configuration
Slack	Slack configuration

API key drivers (GitHub, Notion internal, Linear, Slack): you can skip OAuth env vars. Store the token in step 4 with sanvex:setup. OAuth drivers (Gmail; Notion public integration): set client id, secret, and redirect URI in .env. APP_URL must match your running app and the provider console redirect URL.

# Example: Gmail
GMAIL_CLIENT_ID=....apps.googleusercontent.com
GMAIL_CLIENT_SECRET=...
GMAIL_REDIRECT_URI="${APP_URL}/sanvex/gmail/callback"
GMAIL_SUCCESS_REDIRECT=/

Publishing config/sanvex.php is optional — only if you want to edit core or driver settings in your app:

php artisan vendor:publish --tag=sanvex-config

See Configuration.

Step 4: Connect credentials

Choose one path for your driver.

A — API key or bot token (CLI)

php artisan sanvex:setup github --api-key="ghp_..."
php artisan sanvex:setup notion --api-key="secret_..."
php artisan sanvex:setup slack --bot-token="xoxb-..."

Per-user or per-team credentials:

php artisan sanvex:setup notion --api-key="secret_..." \
  --owner-type=App\\Models\\User --owner-id=1

See Authentication and Tenancy.

B — OAuth (browser)

Built-in login routes (Gmail and Notion today):

Driver	Start URL	When routes are active
Gmail	`/sanvex/gmail/login`	`GMAIL_CLIENT_ID` is set
Notion	`/sanvex/notion/login`	`NOTION_CLIENT_ID` is set or `NOTION_AUTH_TYPE=oauth_2`

Set OAuth env vars (step 3).
Open the login URL in a browser (same app as APP_URL).
Approve access at the provider.
You are redirected back; tokens are stored in sv_accounts.

Default OAuth connections use the global owner. For per-user OAuth, implement your own callback and use oauth()->buildState($owner) — see OAuth. GitHub, Linear, and Slack do not ship login routes yet — store tokens with sanvex:setup or your own OAuth flow.

Step 5: Verify

php artisan tinker --execute="dump(app(\Sanvex\Core\SanvexManager::class)->resolveDriver('github')->isConfigured());"

Replace github with your driver id. Expect true. API call:

use Sanvex\Core\SanvexManager;

app(SanvexManager::class)
    ->resolveDriver('github')
    ->repositories()
    ->list(['per_page' => 5]);

If this fails with 401, the token is missing or invalid — repeat step 4. OAuth routes missing? Run php artisan route:list --path=sanvex and confirm login/callback routes exist. If not, check client id env vars (step 3).

Step 6: Agents (optional)

After step 5 succeeds:

composer require sanvex/laravel-ai
# or
composer require sanvex/mcp

Laravel AI — SanvexAi::driver('github')->tools()
MCP — php artisan sanvex:mcp-stdio

Only register tools when isConfigured() is true for that driver.

Troubleshooting

Symptom	What to check
Driver not in `sanvex:list`	`composer require sanvex/{driver}` completed; clear `php artisan optimize:clear`
`isConfigured()` is false	Step 4 not done, or wrong owner scope (`for($user)` vs global)
OAuth login returns 403	Client id missing or empty in `.env`; run `php artisan config:clear`
OAuth callback “invalid state”	`APP_KEY` set and stable; cache driver working (nonce stored in cache)
Redirect URI mismatch	`APP_URL`, `.env` redirect URI, and provider console must match exactly
Gmail/Google errors	Gmail API enabled; OAuth consent screen configured; redirect URI registered
API 401 after setup	Token revoked or placeholder token; create a new token at the provider
Agent tools empty	Driver not configured; wrong driver id in `SanvexAi::driver(...)`

Usage — resources, webhooks, tenancy patterns
Quickstart — minimal GitHub example
Installation — same steps with extra notes
Drivers — per-driver setup and resources

Getting Started

Concepts

Integrations

Integration guide

Integration guide

Checklist

Step 1: Install core

Step 2: Install a driver

Step 3: Configure `.env`

Step 4: Connect credentials

A — API key or bot token (CLI)

B — OAuth (browser)

Step 5: Verify

Step 6: Agents (optional)

Troubleshooting

Next

​Integration guide

​Checklist

​Step 1: Install core

​Step 2: Install a driver

​Step 3: Configure .env

​Step 4: Connect credentials

​A — API key or bot token (CLI)

​B — OAuth (browser)

​Step 5: Verify

​Step 6: Agents (optional)

​Troubleshooting

​Next

Integration guide

Checklist

Step 1: Install core

Step 2: Install a driver

Step 3: Configure `.env`

Step 4: Connect credentials

A — API key or bot token (CLI)

B — OAuth (browser)

Step 5: Verify

Step 6: Agents (optional)

Troubleshooting

Next