signInCredentials

Sign in to your Aura Auth app using a username or email and password. This is a built-in credential provider that can be used in addition to OAuth providers.

The signInCredentials client method is the primary programmatic entry point for authenticating a user with a username/email and password, from a client-side or browser context.

sign-in.ts

import { authClient } from "@/lib/auth-client"

const output = await authClient.signInCredentials({
  payload: {
    username: "user@example.com",
    password: "password123",
  },
  redirectTo: "/dashboard",
})

Reference

Parameters

Parameter	Type	Required	Description
options	`SignInCredentialsOptions`	Yes	An object containing the credentials payload and request context.

SignInCredentialsOptions

Option	Type	Default	Description
payload	`CredentialsPayload`	—	The credentials for the sign-in attempt. Required — without it there's nothing to authenticate.
redirect	`boolean`	`true`	Whether to redirect via `window.location.assign` (`true`) or return the result as an object (`false`).
redirectTo	`string`	undefined	The URL to redirect to after a successful sign-in.

Returns

Return Type	Description
`Promise<SignInCredentialsReturn<Options>>`	Resolves to an object containing `redirectURL`, `redirect`, and `success` — see Behavior.

Behavior

Cookies are set automatically in the browser context — you don't need to handle them manually.
The CSRF token is automatically loaded and sent with the request — you don't need to handle it manually.
Sign-in success depends entirely on your configured credentials.authorize function on the server, which validates the submitted credentials and returns the User object (or null if invalid).
The return value depends on the redirect option:
- redirect: true (default) — navigates to redirectTo (or the default post-login URL) via window.location.assign.
- redirect: false — resolves to an object with redirectURL, redirect: false, and success, letting you handle navigation yourself.
If the sign-in attempt fails (invalid credentials), redirectURL resolves to null and success is false.

Unlike signIn, redirect defaults to true here — this method navigates to a same-origin URL (redirectTo), so there's no cross-origin CORS concern to opt out of by default.

Setup

lib/auth.ts

import { createAuth } from "@aura-stack/auth"
import { createSecretValue } from "@aura-stack/auth/crypto"

export const auth = createAuth({
  oauth: [],
  credentials: {
    authorize: async ({ credentials }) => {
      if (!credentials || !credentials.username || !credentials.password) {
        return null
      }

      const sub = createSecretValue(10)
      return {
        sub,
        name: "John Doe",
        email: credentials.username,
        image: `https://avatars.dicebear.com/api/initials/${sub}.svg`,
      }
    },
  },
})

Usage

credentials-login.ts

import { authClient } from "@/lib/auth-client"

const output = await authClient.signInCredentials({
  payload: {
    username: "johndoe@example.com",
    password: "password",
  },
})

manual-navigation.ts

import { authClient } from "@/lib/auth-client"

const output = await authClient.signInCredentials({
  payload: {
    username: "alice@example.com",
    password: "password",
  },
  redirect: false,
  redirectTo: "/dashboard",
})

if (output.success) {
  window.location.assign(output.redirectURL)
}