SDK authentication

Sign users in and manage sessions with the EmuView TypeScript SDK.

#SDK authentication

The SDK wraps the auth API with ergonomic methods for sign-up, sign-in, sign-out, and session management.

#Sign up a new user

import { EmuView } from '@emuview/sdk';

const sdk = new EmuView({
	url: 'https://your-api.example.com'
});

const { token, user } = await sdk.auth.signUp({
	email: 'alex@example.com',
	password: 'securePassword123',
	name: 'Alex Chen'
});

console.log(user.id); // "01HXK5M..."
console.log(token); // Session token — the SDK stores it automatically

#Sign in

const { token, user } = await sdk.auth.signIn({
	email: 'alex@example.com',
	password: 'securePassword123'
});

// The SDK stores the session token automatically for future calls

On instances with username sign-in enabled, signIn() also accepts a username or a single identifier field (values containing @ route to email sign-in, everything else to username sign-in):

await sdk.auth.signIn({ username: 'mattsmith', password });
await sdk.auth.signIn({ identifier: loginFormValue, password }); // auto-routes

// Discover what the instance supports before rendering your form
const caps = await sdk.auth.getCapabilities();
// { usernameEnabled, requireEmail, socialProviders }

// Username signup helpers
const free = await sdk.auth.isUsernameAvailable('newname');
await sdk.auth.signUp({ username: 'newname', password, name: 'New Name' }); // email optional when the instance allows it

// Password reset by email or username — always resolves (no account enumeration)
await sdk.auth.requestPasswordReset({ identifier: 'mattsmith', redirectTo: '/reset' });

#Check current session

const session = await sdk.auth.getSession();

if (session) {
	console.log(session.user.email); // "alex@example.com"
	console.log(session.user.role); // "editor"
	console.log(session.session.expiresAt); // ISO timestamp
}

getSession() returns null when the user isn't signed in. Network and server errors still throw, so you can tell "logged out" apart from "API unreachable".

const session = await sdk.auth.getSession();
if (!session) {
	// Not logged in — redirect to the login page
}

#Sign out

await sdk.auth.signOut();
// Session token is cleared

#OAuth sign-in

Supported providers are 'google' and 'github' (each needs its client ID and secret configured on the server):

// Get the consent URL and redirect the user to it
const { url } = await sdk.auth.signInWithProvider('google', {
	callbackURL: '/dashboard'
});

window.location.href = url;

Send a passwordless one-time link (expires after 10 minutes), then verify the token when the user clicks it:

// 1. Send the link
await sdk.auth.sendMagicLink('alex@example.com', {
	callbackURL: '/dashboard'
});

// 2. On the callback page, verify the token from the URL
const token = new URLSearchParams(window.location.search).get('token');
if (token) {
	const { user } = await sdk.auth.verifyMagicLink(token);
	console.log('Signed in as', user.email);
	// The SDK stores the session token automatically
}

#API key authentication

For server-side scripts and automation, use an API key instead of session tokens:

const sdk = new EmuView({
	url: 'https://your-api.example.com',
	auth: { apiKey: 'sk-your-api-key' }
});

// All requests use the API key — no sign-in needed
const users = await sdk.collection('users').list();

#What you learned

  • sdk.auth.signUp() creates a new user and returns { token, user }
  • sdk.auth.signIn() authenticates and stores the session token
  • sdk.auth.signInWithProvider() and sdk.auth.sendMagicLink() cover OAuth and passwordless flows
  • sdk.auth.getSession() returns the current session or null
  • sdk.auth.signOut() clears the session
  • API keys bypass the session system entirely

#Next steps