> ## Documentation Index
> Fetch the complete documentation index at: https://replyke-feat-push-rich-payload-fields.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth

> Sign up, sign in, manage tokens, and handle password and email-verification flows for the end user

The `auth` module handles authentication for the current end user. Use it to register and log in users, rotate tokens, and run password and email-verification flows.

<Note>
  These functions run as the end user — there is no API key and no actor user ID. `signIn`, `signUp`, and `verifyExternalUser` automatically store the returned tokens, and `signOut` clears them (see the auth section of the SDK overview).
</Note>

***

### signUp

Registers a new user and stores the returned tokens.

```typescript theme={null}
const { user, accessToken, refreshToken } = await sublay.auth.signUp({
  email: "user@example.com",
  password: "s3cur3P@ss",
  name: "Alice",
  username: "alice",
});
```

<ParamField body="email" type="string" required>
  The user's email address.
</ParamField>

<ParamField body="password" type="string" required>
  The user's plain-text password (hashed server-side).
</ParamField>

<ParamField body="name" type="string">
  Display name for the user.
</ParamField>

<ParamField body="username" type="string">
  Unique username for the user.
</ParamField>

<ParamField body="avatar" type="string">
  URL of the user's avatar image.
</ParamField>

<ParamField body="bio" type="string">
  Short biography for the user.
</ParamField>

<ParamField body="location" type="{ latitude: number; longitude: number }">
  The user's geographic location.
</ParamField>

<ParamField body="birthdate" type="string">
  The user's birthdate as an ISO 8601 string.
</ParamField>

<ParamField body="metadata" type="Record<string, any>">
  Arbitrary key-value data attached to the user at creation time.
</ParamField>

<ParamField body="secureMetadata" type="Record<string, any>">
  Sensitive key-value data attached to the user, not exposed to clients.
</ParamField>

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

***

### signIn

Authenticates with email/password and stores the returned tokens.

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

<ParamField body="email" type="string" required>
  The user's email address.
</ParamField>

<ParamField body="password" type="string" required>
  The user's password.
</ParamField>

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

***

### signOut

Signs the user out (revokes the refresh token) and clears stored tokens.

```typescript theme={null}
await sublay.auth.signOut();
```

The whole argument is optional.

<ParamField body="refreshToken" type="string">
  The refresh token to revoke. Defaults to the SDK's stored refresh token.
</ParamField>

**Returns** — `Promise<void>`

***

### verifyExternalUser

Exchanges a host-issued user JWT for Sublay tokens and stores them. Use this when your app manages its own auth.

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

<ParamField body="userJwt" type="string" required>
  A JWT issued by your application, containing user identity claims.
</ParamField>

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

***

### requestNewAccessToken

Manually rotates the access token using a refresh token. Normally this is handled automatically on a `403` in SDK-managed mode.

```typescript theme={null}
const { accessToken, refreshToken } = await sublay.auth.requestNewAccessToken();
```

The whole argument is optional.

<ParamField body="refreshToken" type="string">
  The refresh token to exchange. Defaults to the SDK's stored refresh token.
</ParamField>

<Note>
  Persist the new `refreshToken` if one is present (token rotation), or use SDK-managed mode, which does this for you.
</Note>

**Returns** — `Promise<{ accessToken: string; refreshToken?: string }>`

***

### requestPasswordReset

Sends a password-reset email.

```typescript theme={null}
await sublay.auth.requestPasswordReset({ email: "user@example.com" });
```

<ParamField body="email" type="string" required>
  The email address to send the reset link to.
</ParamField>

**Returns** — `Promise<void>`

***

### resetPassword

Completes a password reset using a token from the email.

```typescript theme={null}
await sublay.auth.resetPassword({
  token: resetToken,
  newPassword: "newS3cur3P@ss",
});
```

<ParamField body="token" type="string" required>
  The reset token from the password reset email.
</ParamField>

<ParamField body="newPassword" type="string" required>
  The new password to set for the account.
</ParamField>

**Returns** — `Promise<void>`

***

### changePassword

Changes the authenticated user's password after verifying the current one. Use this for an authenticated "change password" flow, as opposed to the token-based `resetPassword`.

```typescript theme={null}
const { success, message } = await sublay.auth.changePassword({
  password: "currentP@ss",
  newPassword: "newS3cur3P@ss",
});
```

<ParamField body="password" type="string" required>
  The user's current password (verified before the change).
</ParamField>

<ParamField body="newPassword" type="string" required>
  The new password to set.
</ParamField>

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

***

### sendVerificationEmail

Sends (or re-sends) an email-verification message to the authenticated user, delivered as a code or a link.

```typescript theme={null}
const { success } = await sublay.auth.sendVerificationEmail({
  mode: "code",
});
```

The whole argument is optional.

<ParamField body="mode" type="&#x22;code&#x22; | &#x22;link&#x22;">
  `"code"` emails a short token the user enters; `"link"` emails a verification URL. Defaults to `"code"`.
</ParamField>

<ParamField body="tokenFormat" type="&#x22;hex&#x22; | &#x22;numeric&#x22; | &#x22;alpha&#x22; | &#x22;alphanumeric&#x22;">
  Format of the generated token.
</ParamField>

<ParamField body="tokenLength" type="number">
  Length of the generated token.
</ParamField>

<ParamField body="redirectUrl" type="string">
  For `mode: "link"` — where to send the user after the link is verified.
</ParamField>

**Returns** — `Promise<{ success: boolean }>`

***

### verifyEmail

Verifies a user's email using a verification token.

```typescript theme={null}
await sublay.auth.verifyEmail({ token: verificationToken });
```

<ParamField body="token" type="string" required>
  The email verification token.
</ParamField>

**Returns** — `Promise<void>`

***

### requestAccountDeletion

Starts self-service deletion of the authenticated user's account by emailing them a one-time confirmation code (valid for 10 minutes). This does not delete anything on its own — pass the code to [`confirmAccountDeletion`](#confirmaccountdeletion) to finish.

```typescript theme={null}
const { success } = await sublay.auth.requestAccountDeletion();
```

Only works for accounts with an email on file. Accounts without one (e.g. anonymous or foreign-id users) must be deleted server-side with a service key via [`@sublay/node`](/node-sdk/users). The request fails with `auth/no-email-on-file` otherwise.

Takes no arguments.

**Returns** — `Promise<{ success: boolean }>`

***

### confirmAccountDeletion

Verifies the emailed code and **permanently deletes** the authenticated user's account. The cascade matches the service-key delete — entities and comments are kept as hollow shells; everything else owned by the user is removed.

```typescript theme={null}
await sublay.auth.confirmAccountDeletion({ code: "048291" });
```

<Warning>
  Deletion is immediate and irreversible. The user and their session tokens no
  longer exist after this resolves.
</Warning>

<ParamField body="code" type="string" required>
  The one-time confirmation code from the deletion email.
</ParamField>

**Returns** — `Promise<void>`