signInCredentials

Complete API reference for the api.signInCredentials method, providing type-safe password authentication and session generation across all runtimes.

The api.signInCredentials method is the primary programmatic entry point for authenticating a user with a username/email and password. This method runs on the server, so it requires you to pass the request or headers object from your server-side context.

sign-in.ts

import { api } from "@/lib/auth"

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

Reference

Parameters

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

SignInCredentialsAPIOptions

Option	Type	Default	Description
payload	`CredentialsPayload`	—	The credentials for the sign-in attempt. Required — without it there's nothing to authenticate.
request	`Request`	undefined	The request object from the server-side context.
headers	`Headers`	undefined	The headers object from the server-side context.
redirect	`boolean`	`true`	Whether to redirect via the `Location` header (`true`) or return the result as an object (`false`).
redirectTo	`string`	undefined	The URL to redirect to after a successful sign-in.
~~skipCSRFCheck~~	`boolean`	`false`	~~Deprecated~~. This option has been replaced by `doubleSubmitToken` and will be removed in a future release.
doubleSubmitToken	`string`	undefined	Optional CSRF token used to explicitly enable Double-Submit Cookie validation for server-side API functions.

At least one of request or headers is required to construct the incoming URL and validate redirect URLs.

Returns

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

Behavior

Sign-in success depends entirely on your configured credentials.authorize function, which validates the submitted credentials and returns the User object (or null if invalid).
The doubleSubmitToken option enables Double-Submit Cookie validation when calling Aura Auth server-side API functions. By default, API functions execute in a trusted server environment, where browser-based CSRF attacks are not possible because requests originate from server-side code rather than from a user's browser. For that reason, Aura Auth performs the standard CSRF validation but skips the additional Double-Submit Cookie verification.

This option is intended for advanced scenarios where server-side requests should enforce the same CSRF guarantees as browser-initiated requests.

Providing doubleSubmitToken does not replace or disable CSRF protection. It enables the additional Double-Submit Cookie validation on top of the standard CSRF checks already performed by Aura Auth.
The return value depends on the redirect option:
- redirect: true (default) — redirects to redirectTo (or the default post-login URL) via the Location header.
- 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.

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 { api } from "@/lib/auth"

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

manual-navigation.ts

import { api } from "@/lib/auth"

const output = await api.signInCredentials({
  payload: {
    username: "alice@example.com",
    password: "password",
  },
  request: getRequest(),
  redirect: false,
})

if (output.success) {
  redirect(output.redirectURL)
}

double-submit.ts

import { api } from "@/lib/auth"

const output = await api.signInCredentials({
  payload: {
    username: "alice@example.com",
    password: "password",
  },
  request: getRequest(),
  doubleSubmitToken: getDoubleSubmitTokenFromRequest(),
})