Redirecting to authorization...
;
}
```
### Key Points [#key-points]
* **`launch_id`** — Identifies this specific app launch session. Always pass it as the `launch` parameter in the authorization URL.
* **CSRF protection** — Generate a random token and store it in `sessionStorage` keyed by `launch_id`. This prevents cross-site request forgery and isolates multiple tabs.
* **`state` parameter** — Format: `{launchId}:{csrfToken}`. Vim passes it back unchanged in the redirect.
* **Redirect prevention** — Use a `ref` to prevent React StrictMode from triggering a double redirect in development.
## Step 2: Exchange the Authorization Code [#step-2-exchange-the-authorization-code]
After the provider authorizes, Vim redirects back to your `redirect_uri` with a `code` and `state` parameter. Exchange the code for an access token **server-side** to keep your client secret secure.
```typescript
// src/app/api/auth/token/route.ts
import { NextRequest, NextResponse } from 'next/server';
export async function POST(request: NextRequest) {
try {
const { code } = await request.json();
if (!code) {
return NextResponse.json({ error: 'Missing authorization code' }, { status: 400 });
}
const backendUrl = getVimBackendUrl();
const response = await fetch(`${backendUrl}/app-auth/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code,
client_id: process.env.NEXT_PUBLIC_CLIENT_ID,
client_secret: process.env.CLIENT_SECRET,
}),
});
if (!response.ok) {
const errorData = await response.json().catch(() => ({}));
return NextResponse.json(
{ error: errorData.error || 'token_exchange_failed' },
{ status: response.status },
);
}
const tokenData = await response.json();
return NextResponse.json({
access_token: tokenData.access_token,
// Forward id_token: the app passes it to initVimSDK() so getIdToken()
// resolves, which is how it identifies the provider to your backend.
// See Token Lifecycle — omit it only if your app has no backend session.
id_token: tokenData.id_token,
token_type: tokenData.token_type || 'Bearer',
expires_in: tokenData.expires_in,
scope: tokenData.scope,
});
} catch (error) {
console.error('Token exchange error:', error);
return NextResponse.json({ error: 'internal_server_error' }, { status: 500 });
}
}
```
### Security Considerations [#security-considerations]
* **`CLIENT_SECRET` must never be exposed to the browser.** Only use it in server-side code (API routes, server components).
* **Authorization codes are single-use.** If the exchange fails, the provider must re-launch the app.
* **Always validate the `state` parameter** before exchanging the code to prevent CSRF attacks.
## Step 3: Validate and Initialize [#step-3-validate-and-initialize]
On your main app page, validate the OAuth callback, exchange the code, and initialize the SDK:
```typescript
// src/app/app/page.tsx
async function initialize() {
// Validate OAuth parameters
const code = searchParams.get('code');
const stateParam = searchParams.get('state');
if (!code || !stateParam) throw new Error('Missing OAuth parameters');
// Verify CSRF token
const [launchId, csrfToken] = stateParam.split(':');
const storedToken = sessionStorage.getItem(`oauth_state_${launchId}`);
if (csrfToken !== storedToken) throw new Error('CSRF validation failed');
sessionStorage.removeItem(`oauth_state_${launchId}`); // clean up
// Exchange code for token (server-side)
const tokenRes = await fetch('/api/auth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ code }),
});
if (!tokenRes.ok) throw new Error('Token exchange failed');
const { access_token, id_token } = await tokenRes.json();
// Initialize SDK with the token
const sdk = await initVimSDK({
accessToken: access_token,
idToken: id_token, // so getIdToken() resolves — see Token Lifecycle
debug: true,
});
}
```
## Configuration [#configuration]
Create a helper to determine the correct Vim backend URL based on your environment:
```typescript
// src/lib/sdk-config.ts
export function getVimBackendUrl(): string {
if (process.env.NEXT_PUBLIC_VIM_BACKEND_URL) {
return process.env.NEXT_PUBLIC_VIM_BACKEND_URL;
}
switch (process.env.NEXT_PUBLIC_ENV) {
case 'staging':
return 'https://api.stage.getvim.ai';
case 'production':
return 'https://api.getvim.ai';
default:
throw new Error('NEXT_PUBLIC_ENV must be "staging" or "production"');
}
}
```
> **Warning: The Vim API is US-only**
>
> The Vim API is only available to USA server-based instances — IP allow-listing is **not** a
> substitute. Your application server must be hosted within the United States to reach Vim's EHR
> connectivity endpoints. If you develop from outside the US, use a VPN to connect during
> development, but your production app server must still be US-hosted.
### Environment Variables [#environment-variables]
```bash
# .env (checked into source control)
NEXT_PUBLIC_ENV=staging
NEXT_PUBLIC_CLIENT_ID=your_client_id
# .env.local (NOT checked in — contains secrets)
CLIENT_SECRET=your_client_secret
```
| Variable | Side | Description |
| ----------------------------- | --------------- | --------------------------------------------------------------- |
| `NEXT_PUBLIC_ENV` | Client + Server | `staging` or `production` |
| `NEXT_PUBLIC_CLIENT_ID` | Client + Server | OAuth client ID |
| `CLIENT_SECRET` | Server only | OAuth client secret — **never prefix with `NEXT_PUBLIC_`** |
| `NEXT_PUBLIC_VIM_BACKEND_URL` | Client | Optional override for the Vim backend URL |
## Token Lifecycle [#token-lifecycle]
* Access tokens have a limited lifetime (returned in `expires_in`)
* When a token expires, the provider will need to re-launch the app (the extension handles this transparently)
* There is no refresh token flow — each app launch generates a new session
### Vim does not manage your session — you do [#vim-does-not-manage-your-session--you-do]
> **Warning: Keeping the provider signed in is your app's job**
>
> The token Vim issues establishes the **initial** session only — it cannot be extended. Your app
> needs its own session from the moment the SDK is ready, or the provider is signed out the moment
> Vim's token lapses.
The recommended pattern is to exchange the Vim **ID token** for your own application's tokens as
soon as the SDK is ready, then run your own session lifecycle independently of Vim's.
`getIdToken()` resolves only when the SDK is holding an `id_token`, and there are two ways it comes
to hold one:
* **Option 1 (you exchange the code).** Vim's `/app-auth/token` returns `id_token` alongside
`access_token`; forward it through your own endpoint (as Step 2 does) and hand both to the SDK:
`initVimSDK({ accessToken, idToken })`.
* **Option 2 (token endpoint).** The SDK calls your endpoint and captures `id_token` from the
response automatically. Nothing else to do.
Pass `accessToken` on its own and there is no `id_token` to return, so `getIdToken()` rejects with
`ID_TOKEN_UNAVAILABLE`.
```typescript
import { initVimSDK } from '@vimconnect/app-sdk';
// Option 2: no accessToken — the SDK calls your token endpoint and captures the id_token
const sdk = await initVimSDK();
// sessionContext is null until the extension hands off the session seed
if (sdk.sessionContext) {
try {
const { idToken } = await sdk.sessionContext.getIdToken();
const res = await fetch('/api/auth/exchange', {
method: 'POST',
headers: { Authorization: `Bearer ${idToken}` },
});
if (!res.ok) throw new Error(`Exchange failed: ${res.status}`);
// Your backend verified the ID token and issued its own session.
// Prefer a Set-Cookie httpOnly refresh cookie over returning a refresh token
// to page JavaScript — this page runs third-party script from a CDN.
const { accessToken: appToken } = await res.json();
startSession(appToken);
} catch (err) {
// ID_TOKEN_UNAVAILABLE, or your exchange endpoint failed
showSignInError(err);
}
}
```
#### Verifying the ID token [#verifying-the-id-token]
Verify server-side before you trust it. The `id_token` returned by `/app-auth/token` is **signed by
the Vim backend**, not by the Auth0 tenant that authenticates the Vim user — they are different
issuers with different keys:
| Claim | Value |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Issuer (`iss`) | `https://connect.getvim.ai` |
| JWKS | `https://api.getvim.ai/app-auth/.well-known/jwks.json` (staging: `https://api.stage.getvim.ai/...`) |
| Algorithm | `RS256` — pin it; never accept the `alg` the token header asks for |
Check the signature against that JWKS, that `iss` matches, that `aud` matches your client ID, and
that `exp` is in the future. Treat the ID token as a launch-time credential, not a session one: exchange it once, then
authenticate later requests with your own session. Nothing stops a replay within the token's
lifetime, so if that matters to you, record the `jti` you have already accepted.
**Why the split**
* **Separation of concerns** — Vim authenticates the provider for the EHR session; your app owns its own session.
* **Flexibility** — you choose token lifetimes, storage, and refresh policy.
* **Independence** — your session survives Vim token expiry and app re-launches.
**What not to do**
* Don't try to refresh a Vim access token.
* Don't persist Vim access tokens for later use; they are short-lived and scoped to a single launch.
* Don't build a polling or refresh loop against Vim's token endpoint.
* Don't put your own refresh token in `localStorage` — this page loads third-party script, so one XSS turns a short-lived launch into long-lived account access.
---
# Managing Your Developer Account (/docs/developer-account)
This guide covers everything you do in the **Vim Console** — creating an app, filling in its
manifest, getting credentials, submitting for review, and going live. For SDK code, see
[Getting Started](/docs/getting-started).
## Accepting your invitation [#accepting-your-invitation]
You'll receive an email invitation to Vim Connect. It links to a short (about 5 minute)
onboarding wizard — here's what each step asks for.
### Check your inbox [#check-your-inbox]
Look for an email titled **"Vim invited you to join Vim Connect"**. It states what you're being
set up as and links to the onboarding wizard.
Redirecting to authorization...
;
}
export default function LaunchPage() {
return (
Error: {error}
;
if (!sdk) return Connecting to Vim...
;
if (!patient) return Waiting for patient chart...
;
return (
Patient Chart
{JSON.stringify(patient.fields, null, 2)}
No patient selected
;
const demo = patient.fields?.demographics;
return (
{demo?.firstName} {demo?.lastName}
DOB: {demo?.dateOfBirth}