Authentication

The yorauth.auth namespace covers the full user authentication lifecycle: registration, login, logout, token management, passwordless magic links, and multi-factor authentication (TOTP).

The JavaScript SDK is currently in development. This documentation describes the intended API. The package is not yet published to npm.

Register

API endpoint: POST /api/v1/applications/{applicationId}/users/register

typescript

const { data } = await yorauth.auth.register({
  email: 'jane@example.com',
  password: 'super-secret-password',
  name: 'Jane Doe',
  metadata: {               // optional — arbitrary key/value pairs
    plan: 'starter',
    referral_code: 'ABC123',
  },
});

console.log(data.id);    // uuid
console.log(data.email); // 'jane@example.com'

Parameters:

Parameter	Type	Required	Description
`email`	`string`	Yes	User email address
`password`	`string`	Yes	Minimum 8 characters
`name`	`string`	Yes	Display name
`metadata`	`object`	No	Custom key/value pairs stored on the user record

Returns: Promise<{ data: User }> — The created user object (HTTP 201).

After registration, the user will receive a verification email. They must verify their email before they can log in, unless email verification is disabled in your application settings.

Authenticate a user with email and password.

API endpoint: POST /api/v1/applications/{applicationId}/users/login

typescript

const result = await yorauth.auth.login({
  email: 'jane@example.com',
  password: 'super-secret-password',
  rememberMe: true,  // optional — extends refresh token lifetime
});

if (result.mfaRequired) {
  // User has MFA enabled — complete with yorauth.auth.mfa.challenge()
  console.log(result.challengeToken);
  console.log(result.mfaMethods); // ['totp']
} else {
  console.log(result.data.access_token);
  console.log(result.data.refresh_token);
  console.log(result.data.expires_in);  // seconds
  console.log(result.data.user.id);
}

Parameters:

Parameter	Type	Required	Description
`email`	`string`	Yes	User email address
`password`	`string`	Yes	User password
`rememberMe`	`boolean`	No	Default `false`. Extends refresh token lifetime

Returns: Promise<LoginResult> — Either a session with tokens, or an MFA challenge.

When autoRefresh is enabled (default), the SDK stores the refresh token and automatically replaces the access token before it expires. You do not need to call refreshToken() manually.

Logout

Revoke the current refresh token and blacklist the access token.

API endpoint: POST /api/v1/applications/{applicationId}/users/logout

typescript

await yorauth.auth.logout();
// All stored tokens are cleared from storage.

Logout invalidates the refresh token on the server. The current access token is also blacklisted for its remaining TTL. After logout, any subsequent API calls will require re-authentication.

Refresh Token

Manually exchange a refresh token for a new access token and refresh token.

API endpoint: POST /api/v1/applications/{applicationId}/users/token/refresh

typescript

const { data } = await yorauth.auth.refreshToken();

console.log(data.access_token);
console.log(data.refresh_token); // rotation — store the new one
console.log(data.expires_in);

With autoRefresh: true (default), you rarely need to call this method directly. The SDK intercepts 401 responses and refreshes transparently.

Password Reset

Request Reset Link

Send a password reset email to the user.

API endpoint: POST /api/v1/applications/{applicationId}/users/password/forgot

typescript

await yorauth.auth.forgotPassword('jane@example.com');
// Always resolves — never exposes whether the email exists.

Reset Password

Complete the password reset using the token from the email link.

API endpoint: POST /api/v1/applications/{applicationId}/users/password/reset

typescript

await yorauth.auth.resetPassword({
  token: 'token-from-email-link',
  email: 'jane@example.com',
  password: 'new-super-secret-password',
});

Parameters:

Parameter	Type	Required	Description
`token`	`string`	Yes	Token from the password reset email
`email`	`string`	Yes	User email address
`password`	`string`	Yes	New password (minimum 8 characters)

Email Verification

Verify Email

Confirm a user's email address using the token from the verification email.

API endpoint: POST /api/v1/applications/{applicationId}/users/email/verify

typescript

await yorauth.auth.verifyEmail('token-from-verification-email');

Resend Verification Email

API endpoint: POST /api/v1/applications/{applicationId}/users/email/resend

typescript

await yorauth.auth.resendVerificationEmail('jane@example.com');

Magic Links (Passwordless)

Magic links provide a passwordless login flow. The user enters their email, receives a link, and clicking it authenticates them.

Request a Magic Link

API endpoint: POST /api/v1/applications/{applicationId}/users/magic-link

typescript

await yorauth.auth.requestMagicLink({
  email: 'jane@example.com',
  redirectUrl: 'https://myapp.com/auth/callback', // optional
});
// Always resolves — never exposes whether the email exists.

Parameters:

Parameter	Type	Required	Description
`email`	`string`	Yes	User email address
`redirectUrl`	`string`	No	URL to redirect to after verification. Must be an allowed redirect URL configured in your app settings

Verify a Magic Link

After the user clicks the link, pass the token query parameter to this method.

API endpoint: POST /api/v1/applications/{applicationId}/users/magic-link/verify

typescript

// On your callback/verify page:
const params = new URLSearchParams(window.location.search);
const token = params.get('token');

const { data } = await yorauth.auth.verifyMagicLink(token);

console.log(data.access_token);
console.log(data.user.id);
console.log(data.redirect_url); // the redirectUrl from the request, if set

Returns: Promise<{ data: Session }> — Full session with access and refresh tokens.

Multi-Factor Authentication (TOTP)

The SDK supports TOTP-based MFA. The flow has two phases: setup (enroll a new TOTP method) and challenge (verify during login).

MFA Setup

1. Begin TOTP Setup

API endpoint: POST /api/v1/applications/{applicationId}/users/{userId}/mfa/totp/setup

typescript

const { data } = await yorauth.auth.mfa.setupTotp({
  userId: 'user-uuid',
  label: 'My YorAuth App',  // optional — shown in authenticator apps
});

console.log(data.method_id);        // UUID — needed for confirm step
console.log(data.provisioning_uri); // otpauth:// URI for QR code
console.log(data.secret);           // base32 secret for manual entry

Render data.provisioning_uri as a QR code using a library such as qrcode so the user can scan it with their authenticator app.

2. Confirm TOTP Setup

After scanning, the user enters the 6-digit code from their authenticator. This activates MFA and returns one-time backup codes.

API endpoint: POST /api/v1/applications/{applicationId}/users/{userId}/mfa/totp/confirm

typescript

const { data } = await yorauth.auth.mfa.confirmTotp({
  userId: 'user-uuid',
  methodId: data.method_id, // from setup step
  code: '123456',           // 6-digit TOTP code
});

console.log(data.backup_codes); // string[] — show these to the user once

Display backup codes to the user immediately after setup. They cannot be retrieved again. The user should store them securely.

Disable TOTP

API endpoint: DELETE /api/v1/applications/{applicationId}/users/{userId}/mfa/totp

typescript

await yorauth.auth.mfa.disableTotp({
  userId: 'user-uuid',
  password: 'current-password', // re-authentication required
});

Get MFA Status

API endpoint: GET /api/v1/applications/{applicationId}/users/{userId}/mfa/status

typescript

const { data } = await yorauth.auth.mfa.getStatus('user-uuid');

console.log(data.mfa_enabled);           // boolean
console.log(data.methods);               // array of active MFA methods
console.log(data.backup_codes_remaining); // number

Regenerate Backup Codes

API endpoint: POST /api/v1/applications/{applicationId}/users/{userId}/mfa/backup-codes/regenerate

typescript

const { data } = await yorauth.auth.mfa.regenerateBackupCodes({
  userId: 'user-uuid',
  password: 'current-password', // re-authentication required
});

console.log(data.backup_codes); // new codes — previous ones are now invalid

When yorauth.auth.login() returns mfaRequired: true, complete authentication with:

API endpoint: POST /api/v1/applications/{applicationId}/users/mfa/verify

typescript

const loginResult = await yorauth.auth.login({
  email: 'jane@example.com',
  password: 'secret',
});

if (loginResult.mfaRequired) {
  // Prompt the user for their TOTP code or backup code
  const code = prompt('Enter your 6-digit code:');

  const { data } = await yorauth.auth.mfa.challenge({
    challengeToken: loginResult.challengeToken,
    code,
  });

  console.log(data.access_token);
  console.log(data.user.id);
}

Parameters:

Parameter	Type	Required	Description
`challengeToken`	`string`	Yes	The `challengeToken` from the login response
`code`	`string`	Yes	6-digit TOTP code or 8-character backup code

Session State

Check the current authentication state without making an API call:

typescript

const user = yorauth.auth.getUser();  // returns User | null from stored token

const isAuthenticated = yorauth.auth.isAuthenticated(); // boolean

const token = yorauth.auth.getAccessToken(); // string | null

Next Steps

Authorization — Check permissions and manage roles once users are authenticated