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.
Changing or setting a password, self-service account deletion, and linking or listing OAuth identities need the user’s own access token: a service key is refused (403 auth/user-token-required or oauth/user-token-required), so this SDK has no functions for them. Call them from your client with the user’s session. To delete an account from your server, use users.deleteUser.

signUp

Creates a new user account and returns credentials.
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 }>

signIn

Authenticates an existing user and returns fresh credentials.
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.
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.
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.
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.
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.
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. The user signs 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. Contrast Change Password, which a user calls with their own access token: it keeps their current session and can keep one device’s binding.
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.
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.
mode is always required, and it determines what else is required — enforced by TypeScript as a discriminated union, not just documented:
string
required
The user the service key acts as, who receives the verification email.
"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 }>