Configuration

Choose the settings that shape how people sign in, stay signed in, and return to your app.

Start with the four values every app needs

createAuth needs four required settings:

Option	What it means for your app
`clientId`	Identifies your app to the provider
`authorizationEndpoint`	Where people are sent to sign in
`tokenEndpoint`	Where your app exchanges the sign-in result for tokens
`redirectUri`	Where people return after sign-in

These are the essentials for a working PKCE flow.

Use these options to shape the login experience your users see.

Option	Default	Choose it when you want to…
`scope`	—	ask for specific access, such as API scopes or offline access
`state`	—	round-trip app context, such as where login started
`loginMethod`	`"redirect"`	decide whether login should redirect, replace the current page, or use a popup
`autoLogin`	`true`	send signed-out users to login immediately
`clearURL`	`true`	remove sign-in query parameters from the address bar after login
`extraAuthParameters`	—	pass provider-specific options during login
`logoutEndpoint`	—	send people to a provider logout page when they sign out

Good defaults for common products

Use autoLogin: true when your app should always require sign-in.
Use autoLogin: false when you want a landing page, a pricing page, or a visible “Log in” button.
Use loginMethod: "popup" when you want to keep people on the current page during sign-in.

Choose how long sessions should last

These options help you match your provider rules and the experience you want for repeat visitors.

Option	Default	Choose it when you want to…
`tokenExpiresIn`	—	set or override how long the access token should be treated as valid
`refreshTokenExpiresIn`	—	set or override how long refresh can continue
`refreshTokenExpiryStrategy`	`"renewable"`	decide whether refresh time extends with use or ends at a fixed point
`refreshWithScope`	`true`	resend the original scope during refresh when your provider expects it
`extraTokenParameters`	—	send provider-specific values during token exchange or refresh

Choose where session data should live

Option	Default	Choose it when you want to…
`storage`	`"local"`	keep people signed in across tabs and browser restarts, or limit the session to one tab
`storageKeyPrefix`	`"ROCP_"`	separate sessions when you run more than one auth setup on the same domain
`tokenRequestCredentials`	`"same-origin"`	control whether cookies are sent with token requests

Storage guidance

Use "local" when continuity matters more than tab isolation.
Use "session" when you want the session to end with the tab.
Change storageKeyPrefix any time you support multiple providers or environments on the same origin.

The setting that causes the most trouble: `redirectUri`

Your redirectUri must exactly match what you registered with your provider.

If sign-in fails unexpectedly, check these first:

trailing slash differences
http vs https
local development port mismatches
a callback URL that does not load your app

Example setup

const auth = createAuth({
  clientId: "my-client-id",
  authorizationEndpoint: "https://auth.example.com/authorize",
  tokenEndpoint: "https://auth.example.com/token",
  redirectUri: window.location.origin,
  scope: "api:read offline_access",
  autoLogin: false,
  storage: "session",
  tokenExpiresIn: 3600,
  refreshTokenExpiresIn: 86400,
  refreshTokenExpiryStrategy: "absolute",
  loginMethod: "redirect",
  clearURL: true,
  storageKeyPrefix: "myapp_",
});

Working in TypeScript?

You can type the claims you expect in tokenData so your editor helps you use them safely in the UI.

See Typed Token Payloads for a practical example.

On this page