Getting Started

Prerequisites

Before you begin, make sure you have:

A web application with support for OIDC (most frameworks have libraries for this)
HTTPS enabled on your application (required for production)
Your redirect URI(s) ready (the URL Trousseau will redirect to after authentication)

Step 1: Request your credentials

Contact the KeySuite team to register your application. You will need to provide:

Information	Example
Application name	`My Hotel PMS`
Production URL	`https://app.myhotelpms.com`
Staging URL (recommended)	`https://staging.myhotelpms.com`
Redirect URI(s)	`https://app.myhotelpms.com/auth/callback`
Post-logout redirect URI	`https://app.myhotelpms.com/signed-out`
Requested scopes	`openid email profile`
Need provisioning API?	Yes / No

You will receive:

# OIDC Configuration
OIDC_ISSUER=https://auth.keysuite.app/application/o/your-app-slug/
OIDC_CLIENT_ID=your-app-slug-oidc
OIDC_CLIENT_SECRET=your-generated-secret

# Provisioning API (if requested)
TROUSSEAU_API_URL=https://auth.keysuite.app
TROUSSEAU_API_TOKEN=your-api-token

Step 2: Configure your application

Add the OIDC configuration to your application. The exact setup depends on your framework, but you will need these values:

Parameter	Value
Issuer	`https://auth.keysuite.app/application/o/{your-slug}/`
Client ID	`{your-slug}-oidc`
Client Secret	Provided by KeySuite team
Scopes	`openid email profile`
Response type	`code`
Grant type	`authorization_code`
PKCE	Required (use `S256` method)

Discovery endpoint

Trousseau supports OpenID Connect Discovery. Your OIDC library can auto-configure using:

https://auth.keysuite.app/application/o/{your-slug}/.well-known/openid-configuration

This endpoint returns all necessary URLs (authorization, token, userinfo, JWKS, etc.).

Example: Next.js with NextAuth

import NextAuth from "next-auth";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: "trousseau",
      name: "Trousseau",
      type: "oidc",
      issuer: process.env.OIDC_ISSUER,
      clientId: process.env.OIDC_CLIENT_ID,
      clientSecret: process.env.OIDC_CLIENT_SECRET,
    },
  ],
});

Example: Express.js with Passport

import passport from "passport";
import { Strategy as OIDCStrategy } from "passport-openidconnect";

passport.use(
  "trousseau",
  new OIDCStrategy(
    {
      issuer: process.env.OIDC_ISSUER,
      clientID: process.env.OIDC_CLIENT_ID,
      clientSecret: process.env.OIDC_CLIENT_SECRET,
      callbackURL: "https://app.yourapp.com/auth/callback",
      scope: "openid email profile",
    },
    (issuer, profile, done) => {
      // profile.id is the Trousseau user ID (sub claim)
      // profile.emails[0].value is the user's email
      // profile.displayName is the full name
      return done(null, profile);
    }
  )
);

Start your application
Redirect the user to Trousseau's authorization endpoint (your OIDC library handles this)
The user sees the Trousseau login page
After authentication, Trousseau redirects back to your redirect URI with an authorization code
Your application exchanges the code for tokens
Extract user information from the ID token or call the UserInfo endpoint

What the user sees

Existing user (has a password):

Login page — enters email and password
MFA prompt (if configured) — enters TOTP or touches security key
Redirected back to your application — authenticated

New user (first login):

Login page — enters email
Password setup page — creates a password (min 10 chars, complexity enforced)
Redirected back to your application — authenticated

Step 4: Handle the tokens

After successful authentication, you receive:

Token	Purpose	Lifetime
ID Token	User identity (JWT with claims)	5 minutes
Access Token	API access (if needed)	5 minutes
Refresh Token	Obtain new tokens	30 days

Extracting user information

The ID token contains the user's claims. Decode the JWT to access them:

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "jean.dupont@hotel.com",
  "email_verified": true,
  "name": "Jean Dupont",
  "given_name": "Jean",
  "family_name": "Dupont",
  "picture": "https://..."
}

Alternatively, call the UserInfo endpoint:

curl https://auth.keysuite.app/application/o/userinfo/ \
  -H "Authorization: Bearer {access_token}"

Step 5: Implement logout

When your user logs out, redirect them to Trousseau's end-session endpoint to clear the SSO session:

https://auth.keysuite.app/application/o/{your-slug}/end-session/?
  id_token_hint={id_token}&
  post_logout_redirect_uri=https://app.yourapp.com/signed-out

This ensures the user is logged out from both your application and Trousseau.

See the SSO Logout guide for details on RP-Initiated and Backchannel Logout.

What's next?

OIDC Integration Guide

Deep dive into the authorization code flow with PKCE

Scopes & Claims

Full reference of all available claims

Security Best Practices

Checklist for a secure integration

OIDC Integration Guide

Scopes & Claims

Security Best Practices

On this page