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
| Header | Value |
|---|---|
Authorization | Bearer <server-api-key> |
X-Virtneu-Auth-Application | App ID |
X-Virtneu-Auth-Environment | test or production |
Content-Type | application/json for JSON bodies |
Idempotency-Key | Stable 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
| Method | Path | Required scope |
|---|---|---|
| GET | /v1/integration/readiness | sessions:validate + auth:challenge |
| GET | /v1/integration/mail-readiness | auth:challenge |
| POST | /v1/users/lookup | users:read |
| GET | /v1/users/{userId} | users:read |
| DELETE | /v1/users/{userId} | users:delete |
| PATCH | /v1/users/{userId} | users:write |
| POST | /v1/users/batch | users:read |
| GET | /v1/users | users:read |
| POST | /v1/users | auth:register |
| POST | /v1/users/{userId}/access/check | users:status |
| GET | /v1/application/metadata | metadata:read |
| PUT | /v1/application/metadata | metadata:write |
| GET | /v1/users/{userId}/metadata | metadata:read |
| PUT | /v1/users/{userId}/metadata | metadata:write |
| POST | /v1/events/query | auth-events:read |
| POST | /v1/challenges | auth:challenge |
| POST | /v1/challenges/verify | auth:challenge |
| POST | /v1/registrations | auth:register + auth:login |
| POST | /v1/sessions | auth:login |
| POST | /v1/mfa/status | sessions:validate |
| POST | /v1/mfa/enroll | auth:login |
| POST | /v1/mfa/confirm | auth:login |
| POST | /v1/mfa/verify | auth:login |
| POST | /v1/mfa/disable | auth:login + sessions:validate |
| POST | /v1/mfa/recovery-codes | auth:login + sessions:validate |
| POST | /v1/passkeys/list | sessions:validate |
| POST | /v1/passkeys/register/options | auth:login + sessions:validate |
| POST | /v1/passkeys/register/verify | auth:login + sessions:validate |
| POST | /v1/passkeys/authentication/options | auth:login |
| POST | /v1/passkeys/authentication/verify | auth:login |
| POST | /v1/passkeys/delete | auth:login + sessions:validate |
| POST | /v1/passkeys/rename | auth:login + sessions:validate |
| POST | /v1/social/connections | sessions:validate |
| POST | /v1/social/unlink | auth:login + sessions:validate |
| POST | /v1/sessions/validate | sessions:validate |
| POST | /v1/sessions/context | sessions:validate + users:read + metadata:read |
| POST | /v1/sessions/refresh | sessions:refresh |
| POST | /v1/sessions/revoke | sessions:revoke |
| POST | /v1/password-resets | auth:password_reset |
| POST | /v1/users/{userId}/sessions/revoke | users:sessions:revoke |
| GET | /ready | |