Skip to main content
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: "user@example.com",
  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: "user@example.com",
  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: "user@example.com" });
​
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 }>