Users and business credentials
Read users directly and bind your own credentials to current account security state.
Use these backend-only operations with the matching SDK and HTTP contract. Run npm install @virtneu/auth in your backend project for the examples below. Every request is scoped to one app and environment. Grant users:read for directory reads and the separate users:status for account access checks. If an existing API key lacks a required scope, issue a new key and rotate your backend's configured credential.
User identity and exact lookup
user_id is the stable Virtneu Auth identity. Store it on feedback, business credentials, and other business records. external_user_id is your stable external identity; it cannot be changed or reused after permanent deletion. Email is a verified binding, and exact email lookup applies the same trim and lowercase normalization as registration.
| SDK method | HTTP | Scope |
|---|---|---|
lookupUser(input) | POST /v1/users/lookup | users:read |
getUser(userId) | GET /v1/users/{userId} | users:read |
getUsers(userIds) | POST /v1/users/batch | users:read |
listUsers(query) | GET /v1/users | users:read |
checkUserAccess(userId, input) | POST /v1/users/{userId}/access/check | users:status |
lookupUser accepts exactly one of { email } or { external_user_id }. lookupUser and getUser return 404 RESOURCE_NOT_FOUND for a missing user. Email lookup can resolve an identity for password sign-in; the password or login proof must still be verified with createSession. Your login handler should give the browser the same authentication failure for an unknown email and a wrong password.
const { data: user } = await auth.lookupUser({ email: suppliedEmail });
const { data: session } = await auth.createSession({
external_user_id: user.external_user_id,
password: suppliedPassword,
}, { idempotencyKey: loginAttemptKey });User reads return only user_id, external_user_id, email, email_verified, disabled, name, image, created_at, and updated_at. Dates use RFC3339, image can be null, and metadata is read through its separate API. Responses use the usual { data, request_id } envelope and Cache-Control: no-store.
Integrate without a local users table
A generated external_user_id does not require a local business user record. Auth stores that stable identifier, and later backend lookups recover it. Keep only the signup attempt temporarily; your feedback, orders, and credentials reference Auth user_id directly.
- Configure one backend client for the app/environment. Grant
auth:challenge,auth:register,auth:login,sessions:validate, andusers:readfor this flow; mail must be enabled in that environment. - At signup start, generate an opaque
external_user_idonce, plus separate UUID operation keys for challenge, verification, and registration. Save this attempt in a short-lived server-side store bound to the browser's signup session. Reuse the same ID, keys, email, and request parameters after a timeout. A temporary attempt store is not a user directory. - Call
createChallengewith purposeregister, verify the delivered code, then callregisterUserAndSession. This creates the user and first session using one email code. Keep codes, proofs, passwords and tokens out of logs. Persist the verification result in the protected attempt store before creating the account/session; a completion retry loads that saved proof and calls the same completion operation, without verifying the code again after the proof has been consumed. Retain retry material only for its short recovery window. - Put the returned session token in your backend session or a protected HttpOnly, Secure, SameSite cookie, capped at
expires_at. Validate that session when accepting a business write, and take the write'suser_idfrom the validation result rather than a client-supplied author ID. - For a later login, resolve
lookupUser({ email })on the backend. Use the result'sexternal_user_idto issue a login challenge to its verified email, verify the code, then callcreateSession. A lookup is not authentication. Give clients a uniform response for unknown/disabled accounts and failed authentication; do not expose the directory or lookup endpoint anonymously. - Read author names and email with bounded
getUserscalls when rendering business records. A missing user gets a deleted-user fallback; keep historical business records associated with their original ID.
// First request: keep this attempt in a short-lived server-side signup session.
const signup = {
external_user_id: crypto.randomUUID(),
email,
challengeKey: crypto.randomUUID(),
verifyKey: crypto.randomUUID(),
registrationKey: crypto.randomUUID(),
};
const { data: challenge } = await auth.createChallenge({
external_user_id: signup.external_user_id, email: signup.email, purpose: 'register',
}, { idempotencyKey: signup.challengeKey });
// Save challenge.challenge_id with signup before asking for the code.
// Verification request: load the same signup attempt from the backend session.
const { data: proof } = await auth.verifyChallenge({
challenge_id: challenge.challenge_id, code,
}, { idempotencyKey: signup.verifyKey });
// Save proof.authentication_proof in the protected signup attempt BEFORE completion.
// On a completion retry, load it and call only registerUserAndSession below.
const { data: session } = await auth.registerUserAndSession({
external_user_id: signup.external_user_id, email: signup.email,
authentication_proof: proof.authentication_proof,
}, { idempotencyKey: signup.registrationKey });
// Set your protected session cookie. No local users/mapping insert is needed.
// For future business writes, validate the session and store its user_id.The repository's examples/no-local-directory.ts contains type-checked helpers for signup, later email-code login, and an authenticated feedback write. They assume your backend supplies a protected, short-lived attempt store, secure cookie/session handling, CSRF protection and rate limits. Authentication covers session refresh and logout; Troubleshooting defines retry windows.
Existing accounts and email changes
If your application already has users, keep each existing external_user_id stable. Verify which Auth identity belongs to each old business user before migrating association keys to Auth user_id; check the same app/environment and resolve collisions before removing the old mapping. Do not recreate users with new random external IDs or merge accounts merely because email strings match. Historical rows need an explicit, verified migration.
Email is mutable identity data rather than a record key. This release does not expose an email-change endpoint. Do not rewrite business association IDs when an email differs, or delete/re-register as an email-change workaround. If email-change support is added, user_id and external_user_id must remain the stable associations; read the current verified binding from Auth. Permanently deleted external IDs cannot be reused; a later signup uses a new external ID and receives a new Auth user_id, while old business records keep the old ID.
Batch reads
Call getUsers with 1 to 100 distinct IDs. The HTTP body is { user_ids: [...] }. An empty input, duplicates, or more than 100 IDs returns 400 INVALID_REQUEST.
const authorIds = [...new Set(feedback.map(row => row.user_id))];
// Skip the request for an empty set; split larger sets into bounded batches.
const { data } = await auth.getUsers(authorIds);
const authors = new Map(data.users.map(user => [user.user_id, user]));
// data.missing_user_ids identifies authors that no longer exist.The response is { users, missing_user_ids }. Found users and missing IDs each retain their input order. A disabled user remains visible in directory reads. Business records can keep a deleted user's association and display a fallback when the ID is missing.
Stable list pagination
| Query field | Accepted value |
|---|---|
email | Exact normalized email |
external_user_id | Exact external identity |
disabled, email_verified | Boolean; HTTP query text is true or false |
page_size | Integer 1–100; default 25 |
sort | created_at:asc or created_at:desc; default descending |
include_total | Boolean; default false |
cursor | Opaque cursor from the previous page |
List filters can be combined. Sorting uses creation time and user ID to resolve ties. total is returned only with include_total: true; it counts the complete filtered set, independently of the cursor, in the same consistent database batch as the current page.
const query = { disabled: false, page_size: 25, sort: 'created_at:desc' as const };
const first = (await auth.listUsers({ ...query, include_total: true })).data;
if (first.next_cursor) {
const next = (await auth.listUsers({ ...query, cursor: first.next_cursor })).data;
// Render next.users. A null next_cursor marks the end.
}Keep the same filters and sort on subsequent pages. Signed cursors are bound to the app, environment, calling API key, lifecycle generation, filters, and sort. Tampering or changing this context returns 400 INVALID_USER_CURSOR; start a new first page after changing keys. You may change page_size and include_total between pages. Each page is a fresh read, so concurrent insertions and deletions can change the dataset. Pagination does not freeze a cross-request snapshot.
HTTP query parameters cannot be repeated, and unknown fields, unsupported sort values, or boolean text other than true / false return 400 INVALID_REQUEST. Lookup, detail, batch, and account-access endpoints do not accept additional query parameters.
Metadata path filters, metadata sorting, substring search, and event delivery are outside this release. Store business-specific dates in managed_metadata when needed, but only the fields above can be used for list filtering and sorting.
Your own PAT or OAuth credentials
checkUserAccess checks account state; it does not authenticate a person or validate the secret, scope, expiration, or revocation of your business credential.
When issuing a credential, first establish the user's identity through a real Auth session or your existing authentication process. For an Auth session, validate it, read account access, then validate that same session again and require the same user_id. The second validation prevents a disable / restore between reads from binding an invalidated session to a newer account version. Only after every check succeeds should you save the returned security_version alongside the credential's user_id.
// Identity has been authenticated as described above.
const { data: access } = await auth.checkUserAccess(userId);
if (!access.active) throw new Error('Account cannot issue credentials');
// Persist access.security_version with your credential after confirming the session.For each subsequent request, validate your credential's secret, scopes, expiry, and local revocation, then compare its saved version online:
const { data } = await auth.checkUserAccess(binding.user_id, {
expected_security_version: binding.security_version,
});
if (!data.active) throw new Error('Credential is no longer valid');The HTTP request body is {} when obtaining the current version, or { expected_security_version: number } when comparing it. The version must be a nonnegative safe integer. The response is { active: true, security_version } or { active: false }; missing users, disabled users, and version mismatches all return inactive. Missing scopes and disabled environments remain authorization errors; a lifecycle change during the check can return 409 APPLICATION_STATE_CHANGED. These errors do not become active: false.
Disabling / restoring an account, password reset, and revoking all sessions advance its security version. Old business credentials remain invalid after restoration; issue replacements only after fresh authentication. Revoking a single Auth session does not revoke every independent business credential.
A timeout or 503 SERVICE_UNAVAILABLE means this request cannot establish account state. Deny this request and retain the diagnostic error; do not permanently mark a credential revoked merely because Auth was unavailable. Online checks apply changes to subsequent requests. Caching a successful check creates a cache window in your integration.
Keep each business credential associated with the same app and environment as the Auth client that issued its binding. You can keep feedback, orders, and credentials in your own database while reading identity and profile information directly from Auth. Business records need association keys and credential versions; they do not need a second authoritative user directory.