Auth

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.

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",
});

string

required

The user’s email address.

string

required

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

string

Display name for the user.

string

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

object

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

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

Authenticates an existing user and returns fresh credentials.

const { user, accessToken, refreshToken } = await sublay.auth.signIn({
  email: "user@example.com",
  password: "s3cur3P@ss",
});

string

required

The user’s email address.

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 });

string

required

The refresh token to invalidate.

PushDeviceIdentifier

Optional. The device the user is signing out on — { platform: "ios" | "android", token } or { platform: "web", subscription }. When supplied (and the project has the push bundle), the server deletes that user’s push binding for the device in the same transaction as the sign-out. Omit it and the sign-out revokes the token family only, leaving any push binding in place.

await sublay.auth.signOut({
  refreshToken,
  pushDevice: { platform: "ios", token: deviceToken },
});

If the unbind fails, nothing is committed — the call rejects with 500 / auth/device-deregistration-failed and the session survives so you can retry. Never treat a failed signOut as signed out; discarding the credential anyway leaves the user receiving notifications from an account they can no longer reach.A 200 carrying auth/push-unbind-status-unknown is a success, not a failure: the server signed the user out without attempting an unbind because it could not determine whether the project has push devices. See POST /auth/sign-out.

Returns — Promise<void>

requestNewAccessToken

Exchanges a valid refresh token for a new access token.

const { accessToken } = await sublay.auth.requestNewAccessToken({
  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,
});

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" });

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. This revokes every session for that user and removes every push binding they hold, on every device — a reset is the remedy for a suspected compromise, so nothing is spared and there is no field to spare one with. Contrast changePassword, which keeps the calling session and can keep one device’s binding. They sign in again everywhere, and each device re-binds for push on its own once it is next opened. Projects without the push bundle skip the binding step and are otherwise unaffected.

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

string

required

The reset token from the password reset email link.

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 });

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",
  tokenFormat: "numeric",
  tokenLength: 6,
});

mode is always required, and it determines what else is required — enforced by TypeScript as a discriminated union, not just documented:

string

required

The Sublay user ID to send the verification email to.

"code" | "link"

required

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

"hex" | "numeric" | "alpha" | "alphanumeric"

Format of the generated token.

Required when mode: "code" — there’s no default, since "hex" produces a 64-character token no one would want to type.
Optional when mode: "link" (defaults to "hex") — the token sits in a URL, never read by a human, so format doesn’t matter.

number

Length of the generated token (4–12).

Required when mode: "code" and tokenFormat isn’t "hex".
Not allowed when tokenFormat is "hex" — hex ignores length and always produces a fixed 64-character token.
Optional when mode: "link" (defaults to 6).

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). A password change ends every session for that user and deletes every push binding they hold — see Change Password. A service key is not a session, so a call made with one has nothing to spare.

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

string

required

The Sublay user ID whose password to change.

string

required

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

string

required

The new password to set.

object

One device whose push binding should survive the change: { platform: "ios" | "android", token } or { platform: "web", subscription }.A server-side caller normally has no device to name and should omit this — every binding for the user then goes, which is the right default when acting on someone’s behalf. Supply it only when your own client told you which device it is on and you want that one to keep receiving notifications.

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

Getting Started

Modules

signOut

requestNewAccessToken

verifyExternalUser

requestPasswordReset

resetPassword

verifyEmail

sendVerificationEmail

changePassword

​signUp

​signIn

​signOut

​requestNewAccessToken

​verifyExternalUser

​requestPasswordReset

​resetPassword

​verifyEmail

​sendVerificationEmail

​changePassword

signUp

signIn

signOut

requestNewAccessToken

verifyExternalUser

requestPasswordReset

resetPassword

verifyEmail

sendVerificationEmail

changePassword