Quickstart

This guide takes you from an empty account to a Next.js app (App Router) that signs people in through Authio’s hosted login and reads who they are on the server. It uses Auth.js v5 and authio-provider-nextauth, the same provider the Authio console itself signs in with.

Set up Authio

1. 1

   Create a realm

   In the console, open Realms and choose New realm. Give it a name; the realm ID derived from it becomes part of the realm’s issuer and cannot be changed later, so pick something stable such as acme.

   The realm’s overview shows its issuer, the address every client of the realm points at:

   IssuerPlain text

   https://authio.api.hyperio.tech/realms/acme

2. 2

   Create a client for your app

   Open Clients and choose New client. Pick the realm you just created, give the client an ID (lowercase letters, numbers and hyphens, for example acme-web) and a display name — the name your users see on the sign-in screen.

   Under redirect URIs, add the address Auth.js receives the sign-in on:

   Redirect URIPlain text

   http://localhost:3000/api/auth/callback/authio

   The client secret is shown once, right after the client is created. Copy it now; if you lose it, rotate it from the client’s view.

Connect your app

1. 1

   Install the packages

   TerminalBash

   npm install next-auth@beta authio-provider-nextauth

2. 2

   Add your credentials

   Auth.js reads the provider’s settings from variables prefixed with AUTH_AUTHIO_. AUTH_SECRET is a different thing: the key that encrypts the session cookie. Generate it with npx auth secret and never reuse the client secret for it.

   .env.local.env

   AUTH_SECRET=generated-by-npx-auth-secret
   AUTH_AUTHIO_ISSUER=https://authio.api.hyperio.tech/realms/acme
   AUTH_AUTHIO_ID=acme-web
   AUTH_AUTHIO_SECRET=YOUR_CLIENT_SECRET

3. 3

   Configure Auth.js

   Register the Authio provider and expose Auth.js’s route handlers. With the variables above in place, the provider needs no options.

   auth.tsapp/api/auth/[...nextauth]/route.ts

   auth.tsTypeScript

   import NextAuth from 'next-auth'
   import Authio from 'authio-provider-nextauth/v5'
   
   export const { handlers, signIn, signOut, auth } = NextAuth({
     providers: [Authio],
   })

4. 4

   Add sign-in and sign-out

   Read the session on the server with auth() and use server actions for the two buttons:

   app/page.tsxTypeScript

   import { auth, signIn, signOut } from '@/auth'
   
   export default async function Home() {
     const session = await auth()
   
     if (!session?.user) {
       return (
         <form
           action={async () => {
             'use server'
             await signIn('authio')
           }}
         >
           <button type="submit">Sign in</button>
         </form>
       )
     }
   
     return (
       <form
         action={async () => {
           'use server'
           await signOut()
         }}
       >
         <p>Signed in as {session.user.email}</p>
         <button type="submit">Sign out</button>
       </form>
     )
   }

5. 5

   Try it

   Run npm run dev, open http://localhost:3000 and choose Sign in. You land on the realm’s hosted login. Sign in with a user you added to the realm in the console, and you are back in your app with a session.

Troubleshooting

Next steps