post `/users/sso`

Single Sign On (SSO)

Base URL https://api.vseepreview.com/api_v3 · operationId ssoUser

Authentication: API Key + Secret — Requires API Key and API Secret issued during onboarding.

Single Sign On for patient and provider. This is disabled by default — contact admin@vsee.com to request it.

SSO will create a user record on VSee side when you first call this API and will map to and return the existing user record for further requests.

Use ?fields=vsee to include VSee ID and token in the response (for Browser Call SDK workflow).

Important: SSO is disabled by default. Contact admin@vsee.com to request activation.

SSO creates a user record on VSee side on first call and returns the existing user for subsequent requests using the same code.

Tip: Use POST /users/sso?fields=vsee to include the VSee ID and token in the response for Browser Call SDK workflow.

E-Prescribe Requirements

To enable e-prescribing for a patient (type=200), the following additional fields are required in the SSO call:

gender (string): male or female
street_addr (string): Patient's street address
city (string): Patient's city
state (string): Two-letter state abbreviation
zip (string): ZIP code
phone (string): Phone number
dob (string): Date of birth in YYYY-MM-DD format

SSO Types

Guest SSO (type=600): Creates a one-time guest user. No code required.
Patient SSO (type=200): Creates/returns a registered patient. code is required (max 128 chars).
Provider SSO (type=400): Creates/returns a provider. code is required (max 128 chars).

Response Token

Use data.token.token to redirect user to VSee Clinic portal via the /auth endpoint.

Parameters

Name	In	Type	Required	Enum	Description
`X-ApiKey`	header	string	yes		API Key (e.g. your_api_key)
`X-ApiSecret`	header	string	yes		API Secret (e.g. your_api_secret)
`X-AccountCode`	header	string	yes		Account code (e.g. vclinic)
`fields`	query	string	no	vsee	Include additional fields in response. Use `vsee` to get VSee ID and token for Browser Call SDK.

Request body

Content type: multipart/form-data

Field	Type	Required	Enum	Description
`first_name`	string	yes		User's first name
`last_name`	string	yes		User's last name
`type`	integer	yes	200, 400, 600	User type: 200 (Member/Patient), 400 (Provider), 600 (Guest)
`code`	string	no		Required if type is 200 or 400. Max length 128 characters. A unique user identifier on your end. VSee stores this code and returns the same user on subsequent SSO calls.
`dob`	string	no		Date of birth in YYYY-MM-DD format
`email`	string	no		User email address
`username`	string	no		Optional — system will generate one as fallback
`disable_emails`	integer	no	0, 1	Set to `1` to disable all email notifications
`gender`	string	no	male, female	Required for e-prescribe. `male` or `female`
`street_addr`	string	no		Required for e-prescribe
`city`	string	no		Required for e-prescribe
`state`	string	no		Required for e-prescribe. Two-letter state abbreviation
`zip`	string	no		Required for e-prescribe
`phone`	string	no		Required for e-prescribe

Example:

{
  "first_name": "John",
  "last_name": "Smith",
  "type": 600
}

Responses

`200` — Successful SSO response

Guest SSO — Guest SSO response

{
  "data": {
    "id": "10008",
    "code": "57d76ada0bb444f9b3057855ac1f0144",
    "first_name": "John",
    "last_name": "Smith",
    "username": "57d76ad979b843e6973e7855ac1f0144",
    "vseeid": "conciergedev+57d76ad979b843e6973e7855ac1f0144",
    "dob": "1990-01-01",
    "active": true,
    "tos": false,
    "subtype": "",
    "token": {
      "user_id": "10008",
      "token": "0437c1ce3b7079906e2ff247aad1adda",
      "expiry": 1473821786,
      "refresh_token": {
        "user_id": "10008",
        "token": "2693615fd2a46edf13334b3f35580e26",
        "expiry": 1476327386,
        "created": 1473735386
      }
    }
  }
}

Patient SSO — Patient SSO response

{
  "data": {
    "id": "10008",
    "code": "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
    "first_name": "John",
    "last_name": "Smith",
    "username": "57d76ad979b843e6973e7855ac1f0144",
    "vseeid": "conciergedev+57d76ad979b843e6973e7855ac1f0144",
    "active": true,
    "tos": false,
    "subtype": "",
    "token": {
      "user_id": "10008",
      "token": "0437c1ce3b7079906e2ff247aad1adda",
      "expiry": 1473821786,
      "refresh_token": {
        "user_id": "10008",
        "token": "2693615fd2a46edf13334b3f35580e26",
        "expiry": 1476327386,
        "created": 1473735386
      }
    }
  }
}

Provider SSO — Provider SSO response

{
  "data": {
    "id": "10008",
    "code": "cd978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
    "first_name": "John",
    "last_name": "Provider",
    "username": "57d76ad979b843e6973e7855ac1f0144",
    "vseeid": "anton+johnsmithprovider@vseelab.com",
    "email": "anton+johnsmithprovider@vseelab.com",
    "active": true,
    "tos": false,
    "subtype": "",
    "token": {
      "user_id": "10008",
      "token": "0437c1ce3b7079906e2ff247aad1adda",
      "expiry": 1473821786,
      "refresh_token": {
        "user_id": "10008",
        "token": "2693615fd2a46edf13334b3f35580e26",
        "expiry": 1476327386,
        "created": 1473735386
      }
    }
  }
}

`400` — Bad Request

{
  "code": 404,
  "message": "Sorry, this page is not available."
}

`401` — Unauthorized

{
  "code": 404,
  "message": "Sorry, this page is not available."
}

Machine-readable: OpenAPI JSON (operationId: ssoUser)

post /users/sso