Menu

DoneIsBetter SSO

Browse documentation sections.

Getting Started

Introduction
Quick Start
Installation

Integration Guide

Authentication
Session Management
Error Handling

API Reference

Endpoints
Response Format
Error Codes

Examples

React
Vue.js
Vanilla JS

Security

Best Practices
CORS Configuration
Permissions
GitHubSupport

API Reference

SSO API Reference

Reference surface for OAuth, hosted auth, public sessions, and permission-management contracts.

API Version

5.29.0

Overview

The SSO API combines OAuth 2.0 / OpenID Connect endpoints, public-user authentication, session-validation endpoints, and permission-management APIs.

Current contract

OAuth token issuance happens through /api/oauth/*. Public login endpoints set a cookie-backed session and do not replace the OAuth token flow.

API Areas

OAuth / OIDC

  • GET /api/oauth/authorize - start authorization-code flow
  • POST /api/oauth/token - exchange code or refresh token
  • GET /api/oauth/userinfo - get user claims from access token
  • POST /api/oauth/revoke - revoke token
  • GET /api/oauth/logout - logout from the hosted SSO session
  • GET /.well-known/openid-configuration - OIDC discovery document
  • GET /.well-known/jwks.json - JWKS for token verification

Public Authentication

  • POST /api/public/register - create account or add password to a social-only account
  • POST /api/public/login - password login, sets public-session
  • POST /api/public/request-magic-link - request email magic link
  • GET /api/public/magic-login - consume magic-link token
  • POST /api/public/verify-pin - complete a PIN-gated login
  • GET /api/public/session - validate public session cookie

Social Login

  • GET /api/auth/google/login
  • GET /api/auth/google/callback
  • GET /api/auth/facebook/login
  • GET /api/auth/facebook/callback

Permission APIs

  • GET /api/users/[userId]/apps/[clientId]/permissions - read a permission record
  • PUT /api/users/[userId]/apps/[clientId]/permissions - app-managed permission update
  • DELETE /api/users/[userId]/apps/[clientId]/permissions - app-managed revoke
  • POST /api/users/[userId]/apps/[clientId]/request-access - create pending access request
  • PUT /api/admin/users/[userId]/apps/[clientId]/permissions - admin-managed permission update
  • DELETE /api/admin/users/[userId]/apps/[clientId]/permissions - admin-managed revoke

Important Behavior

  • Canonical permission roles are none, user, and admin.
  • Canonical permission statuses are pending, approved, and revoked.
  • Public session validation is cookie-based.
  • OAuth-protected permission writes require a client token with manage_permissions.
  • Access-request creation requires a user-bound token whose subject and client both match the request target.
Endpoint reference