Auth

Sign users up, sign them in, manage tokens, and handle password resets from your server

The auth module handles user authentication flows server-side. This is useful for custom onboarding pipelines, admin-initiated account creation, token introspection, and password management.

All auth functions operate on behalf of your project. The caller is your server, authenticated via API key — not an end user.

---

signUp

Creates a new user account and returns credentials.

const { user, accessToken, refreshToken } = await sublay.auth.signUp({
  email: "[e-mail]",
  password: "s3cur3P@ss",
  name: "Alice",
  username: "alice",
});

email · string · required

The user’s email address.

password · string · required

The user’s plain-text password (hashed server-side).

name · string

Display name for the user.

username · string

Unique username. Must be available — check with users.checkUsernameAvailability first.

metadata · object

Arbitrary key-value data attached to the user at creation time.

Returns — Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>

---

signIn

Authenticates an existing user and returns fresh credentials.

const { user, accessToken, refreshToken } = await sublay.auth.signIn({
  email: "[e-mail]",
  password: "s3cur3P@ss",
});

email · string · required

The user’s email address.

password · string · required

The user’s password.

Returns — Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>

---

signOut

Invalidates a refresh token, ending the user’s session.

await sublay.auth.signOut({ refreshToken });

refreshToken · string · required

The refresh token to invalidate.

Returns — Promise<void>

---

requestNewAccessToken

Exchanges a valid refresh token for a new access token.

const { accessToken } = await sublay.auth.requestNewAccessToken({
  refreshToken,
});

refreshToken · string · required

A valid, non-expired refresh token.

Returns — Promise<{ accessToken: string }>

---

verifyExternalUser

Verifies a signed JWT representing an externally-authenticated user and returns Sublay credentials. Use this when your application manages its own auth and you want to associate users with Sublay.

const { user, accessToken, refreshToken } = await sublay.auth.verifyExternalUser({
  userJwt: signedJwt,
});

userJwt · string · required

A JWT signed with your project’s signing secret, containing user identity claims.

Returns — Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>

---

requestPasswordReset

Sends a password reset email to the specified address.

await sublay.auth.requestPasswordReset({ email: "[e-mail]" });

email · string · required

The email address to send the reset link to.

Returns — Promise<void>

---

resetPassword

Completes a password reset using a token from the reset email.

await sublay.auth.resetPassword({
  token: resetToken,
  newPassword: "newS3cur3P@ss",
});

token · string · required

The reset token from the password reset email link.

newPassword · string · required

The new password to set for the account.

Returns — Promise<void>

---

verifyEmail

Marks a user’s email address as verified using a token from the verification email.

await sublay.auth.verifyEmail({ token: verificationToken });

token · string · required

The email verification token.

Returns — Promise<void>

---

sendVerificationEmail

Sends (or re-sends) an email-verification message to a user. Verification can be delivered as a short code or as a clickable link.

const { success } = await sublay.auth.sendVerificationEmail({
  userId: "usr_abc123",
  mode: "code",
});

userId · string · required

The Sublay user ID to send the verification email to.

mode · string

"code" emails a short token the user enters; "link" emails a verification URL. Defaults to "code".

tokenFormat · string

Format of the generated token: "hex", "numeric", "alpha", or "alphanumeric".

tokenLength · number

Length of the generated token.

redirectUrl · string

For mode: "link" — where to send the user after the link is verified.

Returns — Promise<{ success: boolean }>

---

changePassword

Changes a user’s password, verifying their current password first. Use this for an authenticated “change password” flow (as opposed to the token-based resetPassword).

const { success, message } = await sublay.auth.changePassword({
  userId: "usr_abc123",
  password: "currentP@ss",
  newPassword: "newS3cur3P@ss",
});

userId · string · required

The Sublay user ID whose password to change.

password · string · required

The user’s current password (verified before the change).

newPassword · string · required

The new password to set.

Returns — Promise<{ success: boolean; message: string }>