Getting Started

DoneIsBetter SSO Documentation

Current runtime guide for OAuth, hosted auth, and shared-domain session validation.

API Version

5.29.0

Recommended default

Use OAuth 2.0 Authorization Code flow with OIDC claims. Public login endpoints create cookie-backed sessions, but they do not replace the OAuth token flow.

Design / UI / UX SSOT lives in the shared General Design System. Local styling in this repo should be treated as migration-state implementation, not the long-term design source of truth.

Current Capabilities

OAuth 2.0 / OpenID Connect authorization server
Hosted public-user authentication with password, magic link, PIN, Google, and Facebook
Centralized per-app authorization through appPermissions
Cookie-based SSO for shared subdomain deployments

Canonical Runtime Contract

App-permission roles: none, user, admin
App-permission statuses: pending, approved, revoked
Admin cookie: admin-session
Public cookie: public-session
Apple Sign In, passkeys, SAML, and SCIM are not implemented today

Choose Your Integration

OAuth2 / OIDC

Use this for most apps, especially external domains, SPAs, mobile apps, and server applications.

GET /api/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/auth/callback
  &response_type=code
  &scope=openid%20profile%20email%20offline_access
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Cookie-Based SSO
Use this only when your app shares the configured cookie domain with the SSO service.
```
GET /api/public/session
Cookie: public-session=...
```
Permission-Aware Integrations
App access is not based on authentication alone. Check or manage the user’s permission record per client.
```
GET /api/users/{userId}/apps/{clientId}/permissions
Authorization: Bearer ACCESS_TOKEN
```

Key Endpoints

GET /api/oauth/authorize
POST /api/oauth/token
GET /api/oauth/userinfo
GET /api/public/session
POST /api/public/login
POST /api/public/request-magic-link
POST /api/users/[userId]/apps/[clientId]/request-access