Authentication Guide

Learn how to authenticate with the VSee Clinic API. Different endpoints require different credentials.

Overview

The VSee Clinic API uses header-based authentication. Every request must include an X-AccountCode header to identify your clinic. Depending on the endpoint, you'll also need one of several token types.

Common mistake: Using an SSO access token or user login token to call admin endpoints (like Create Room). Admin endpoints require the Clinic Admin API Token from your dashboard, not a user session token.

Token Types

Token Type	How to Get It	Header(s)	When to Use
Clinic Admin API Token	Admin Dashboard → Developers → App → Edit App	`X-ApiToken` + `X-AccountCode`	Server-to-server admin operations: creating rooms, managing users, account settings, webhooks, recordings
User Access Token	Response from `POST /users/login` or `POST /users/sso`	`X-ApiToken` + `X-AccountCode`	Acting on behalf of a logged-in user: get/update profile, visits, EMR, logout
API Key + Secret	Issued during API access onboarding	`X-ApiKey` + `X-ApiSecret` + `X-AccountCode`	SSO endpoints only (`POST /users/sso`)
Account Code Only	Issued during onboarding	`X-AccountCode`	Public/pre-login endpoints: login, activate user, reset password, settings
None	N/A	—	A few endpoints require no auth headers (e.g., `GET /auth`)

Clinic Admin Token vs User Token

Both the Clinic Admin API Token and User Access Token are sent in the same X-ApiToken header, but they are different values with different permissions:

Clinic Admin API Token

• Generated in the Admin Dashboard under Developers → App → Edit App
• Does not expire (until regenerated)
• Has full admin permissions for your clinic
• Used for server-to-server integrations
• Never expose in client-side code

User Access Token

• Returned from login or SSO endpoints
• Expires after a period of inactivity
• Scoped to the authenticated user's permissions
• Used for user-facing actions
• Can be refreshed with POST /users/token/refresh

Which Token Do I Need?

Are you calling the SSO endpoint? → Use API Key + Secret

Are you managing clinic resources (rooms, webhooks, recordings, account settings)? → Use Clinic Admin API Token

Are you doing something on behalf of a logged-in user? → Use User Access Token

Are you calling a public/pre-login endpoint (login, settings, activate)? → Use Account Code only

Auth Badges in This Documentation

Each endpoint in the API Reference displays a colored badge indicating which authentication method it requires:

Admin TokenUser TokenAPI Key + SecretAccount Code OnlyNo Auth

Example: Creating a Room (Admin Token)

This is one of the most common integration points. Notice the X-ApiToken value here must be the Clinic Admin API Token from your dashboard — not a user session token.

curl -X POST https://api.vsee.me/api_v3/rooms \
  -H "X-AccountCode: YOUR_CLINIC_CODE" \
  -H "X-ApiToken: YOUR_CLINIC_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Patient Consultation",
    "members": ["doctor@example.com"]
  }'