Virtneu Auth Docs

HTTP API reference

Request headers, session validation example, and the full OpenAPI contract.

Base URL: https://auth-api.virtneu.com

The 0.7.0 API contract contains 41 operations, including hosted and embedded passkey contexts, passkey rename, MFA, social connections, combined session context and readiness endpoints. SDK 0.7.0 is published with 16 backend security methods and a separate browser entry. Embedded login selects the context of an existing operation; it does not add another HTTP operation. New capabilities still require the matching API deployment and schema; the package receipt does not establish production API activation. Immutable 0.6.0 keeps 41 operations and 15 security methods, and 0.5.0 keeps its 40-operation contract. Download the OpenAPI specification for parameters, schemas and errors, and confirm the matching API deployment and schema before upgrading consumers. The immutable 0.4.0 and 0.3.0 packages retain their historical 26- and 23-operation contracts. Business OAuth / OIDC and its independent account-security request use a separate protocol contract.

Request headers

HeaderValue
AuthorizationBearer <server-api-key>
X-Virtneu-Auth-ApplicationApp ID
X-Virtneu-Auth-Environmenttest or production
Content-Typeapplication/json for JSON bodies
Idempotency-KeyStable key for operations marked as requiring it in OpenAPI

The key must belong to the specified app and environment and include the endpoint's scope. Keep credentials on your server.

Use the header names above exactly. The legacy X-VAuth-Application and X-VAuth-Environment names do not authorize requests. Success and error responses use Cache-Control: no-store; the JSON request_id matches the response's X-Request-Id.

Validate a session

curl https://auth-api.virtneu.com/v1/sessions/validate \
  -H "Authorization: Bearer $VAUTH_SERVICE_CREDENTIAL" \
  -H "X-Virtneu-Auth-Application: $VAUTH_APPLICATION_ID" \
  -H "X-Virtneu-Auth-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{"session_token":"integration-check-unknown-session"}'

An authorized request using this sample returns HTTP 200 with data.active: false and a request_id. For production handling, see Authentication and sessions and Troubleshooting.

Endpoints

MethodPathRequired scope
GET/v1/integration/readinesssessions:validate + auth:challenge
GET/v1/integration/mail-readinessauth:challenge
POST/v1/users/lookupusers:read
GET/v1/users/{userId}users:read
DELETE/v1/users/{userId}users:delete
PATCH/v1/users/{userId}users:write
POST/v1/users/batchusers:read
GET/v1/usersusers:read
POST/v1/usersauth:register
POST/v1/users/{userId}/access/checkusers:status
GET/v1/application/metadatametadata:read
PUT/v1/application/metadatametadata:write
GET/v1/users/{userId}/metadatametadata:read
PUT/v1/users/{userId}/metadatametadata:write
POST/v1/events/queryauth-events:read
POST/v1/challengesauth:challenge
POST/v1/challenges/verifyauth:challenge
POST/v1/registrationsauth:register + auth:login
POST/v1/sessionsauth:login
POST/v1/mfa/statussessions:validate
POST/v1/mfa/enrollauth:login
POST/v1/mfa/confirmauth:login
POST/v1/mfa/verifyauth:login
POST/v1/mfa/disableauth:login + sessions:validate
POST/v1/mfa/recovery-codesauth:login + sessions:validate
POST/v1/passkeys/listsessions:validate
POST/v1/passkeys/register/optionsauth:login + sessions:validate
POST/v1/passkeys/register/verifyauth:login + sessions:validate
POST/v1/passkeys/authentication/optionsauth:login
POST/v1/passkeys/authentication/verifyauth:login
POST/v1/passkeys/deleteauth:login + sessions:validate
POST/v1/passkeys/renameauth:login + sessions:validate
POST/v1/social/connectionssessions:validate
POST/v1/social/unlinkauth:login + sessions:validate
POST/v1/sessions/validatesessions:validate
POST/v1/sessions/contextsessions:validate + users:read + metadata:read
POST/v1/sessions/refreshsessions:refresh
POST/v1/sessions/revokesessions:revoke
POST/v1/password-resetsauth:password_reset
POST/v1/users/{userId}/sessions/revokeusers:sessions:revoke
GET/ready

On this page