GitHubSupport

DoneIsBetter SSO API Reference

API Version: 5.24.0

Getting Started

⚠️ OAuth 2.0 API
This SSO uses standard OAuth 2.0 Authorization Code Flow. No proprietary client library required.

The DoneIsBetter SSO API is a fully OAuth 2.0 compliant authorization server. This reference provides complete documentation for all endpoints, token structures, and integration patterns.

Quick Start Example

// Step 1: Redirect user to authorization endpoint
window.location.href = 
  'https://sso.doneisbetter.com/api/oauth/authorize' +
  '?client_id=YOUR_CLIENT_ID' +
  '&redirect_uri=https://yourapp.com/auth/callback' +
  '&response_type=code' +
  '&scope=openid profile email';

// Step 2: Exchange authorization code for tokens (server-side)
const response = await fetch('https://sso.doneisbetter.com/api/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCode,
    client_id: process.env.SSO_CLIENT_ID,
    client_secret: process.env.SSO_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/auth/callback'
  })
});

const { access_token, id_token } = await response.json();

API Endpoint Categories

OAuth 2.0 Authorization

Standard OAuth 2.0 endpoints with PKCE support for authentication and token management:

  • GET /api/oauth/authorize - Start OAuth flow, get authorization code (PKCE supported)
  • POST /api/oauth/token - Exchange code for access/refresh tokens
  • POST /api/oauth/revoke - Revoke access or refresh token
  • GET /api/oauth/logout - Logout and clear SSO session with redirect

View OAuth endpoints →

OpenID Connect Discovery

Standard OIDC discovery endpoints:

  • GET /.well-known/openid-configuration - OIDC discovery document
  • GET /.well-known/jwks.json - JSON Web Key Set for token verification

View OIDC endpoints →

Public User API

User registration, login, and session management:

  • POST /api/public/register - Register new user account
  • POST /api/public/login - Direct login (email + password)
  • GET /api/public/session - Validate Bearer token session
  • POST /api/public/request-magic-link - Request passwordless magic link
  • GET /api/public/magic-login - Consume magic link token
  • POST /api/public/verify-pin - Verify PIN code during login
  • GET /api/public/validate - Validate session cookie (subdomain SSO)

View public endpoints →

Social Login API

Social provider authentication (Facebook, Google coming soon):

  • GET /api/auth/facebook/login - Initiate Facebook OAuth flow
  • GET /api/auth/facebook/callback - Facebook OAuth callback handler

Users authenticate via social provider, accounts created automatically with profile data.

Admin API

Administrative endpoints (requires SSO admin authentication):

  • POST /api/admin/login - Admin authentication
  • GET /api/admin/users - List all admin users
  • GET /api/admin/public-users - List public users with login methods
  • GET /api/admin/oauth-clients - List OAuth clients
  • POST /api/admin/oauth-clients - Create OAuth client (super-admin)
  • PATCH /api/admin/oauth-clients/[clientId] - Update OAuth client
  • POST /api/admin/oauth-clients/[clientId]/regenerate-secret - Regenerate client secret
  • GET /api/admin/app-permissions/[userId] - Get user's app permissions
  • POST /api/admin/app-permissions/[userId] - Grant app access
  • DELETE /api/admin/app-permissions/[userId] - Revoke app access

View admin endpoints →

Token Structures

SSO issues three types of tokens:

Access Token (JWT)

Used for API authentication. Include in Authorization: Bearer header.

// Decoded payload:
{
  "sub": "user-uuid",
  "iss": "https://sso.doneisbetter.com",
  "aud": "your-client-id",
  "exp": 1234571490,
  "iat": 1234567890
}

// Expiry: 1 hour
// Usage: Authorization: Bearer <access_token>

ID Token (JWT)

Contains user identity including social login data. Decode to get user info.

// Decoded payload:
{
  "sub": "user-uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "email_verified": true,
  "picture": "https://...",  // Profile picture (if available)
  "iss": "https://sso.doneisbetter.com",
  "aud": "your-client-id",
  "exp": 1234571490,
  "iat": 1234567890
}

// Received once during token exchange
// Works for all authentication methods (password, magic link, social login)

Refresh Token (JWT)

Used to obtain new access tokens without re-authentication.

// Opaque to clients, don't decode
// Expiry: 30 days of inactivity
// Usage: POST /api/oauth/token with grant_type=refresh_token

View complete response formats →

Error Handling

The API uses standard HTTP status codes and OAuth 2.0 error codes:

HTTP Status Codes

  • 200 OK - Request successful
  • 400 Bad Request - Invalid parameters or request body
  • 401 Unauthorized - Invalid or expired token, authentication required
  • 403 Forbidden - Valid auth but insufficient permissions
  • 404 Not Found - Resource doesn't exist
  • 500 Internal Server Error - Server error

OAuth 2.0 Error Response

// Authorization endpoint errors (query params)
https://yourapp.com/callback?error=access_denied&error_description=User+denied+authorization

// Token endpoint errors (JSON)
{
  "error": "invalid_grant",
  "error_description": "Authorization code expired or already used"
}

// API endpoint errors (JSON)
{
  "error": {
    "code": "APP_PERMISSION_DENIED",
    "message": "User does not have permission to access this application",
    "status": "pending"
  }
}

View complete error reference →

CORS Configuration

OAuth authorization and token endpoints require proper CORS configuration. Your OAuth client's redirect URIs are automatically whitelisted.

// Browser automatically includes:
Origin: https://yourapp.com

// SSO responds with:
Access-Control-Allow-Origin: https://yourapp.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Note: Token exchange MUST happen server-side (no CORS issues).

OAuth 2.0 Libraries

Use standard OAuth 2.0 libraries for your platform. No proprietary client library needed.

Recommended Libraries

  • Node.js
    • passport-oauth2 - Passport.js OAuth 2.0 strategy
    • next-auth - NextAuth.js with custom OAuth provider
    • simple-oauth2 - Lightweight OAuth 2.0 client
  • Python
    • authlib - Comprehensive OAuth library
    • requests-oauthlib - OAuth for requests library
  • Go
    • golang.org/x/oauth2 - Official Go OAuth 2.0 package
  • Java
    • spring-security-oauth2 - Spring Security OAuth

OpenID Connect Discovery

Configure libraries using OIDC discovery endpoint:

// Discovery URL
https://sso.doneisbetter.com/.well-known/openid-configuration

// Auto-configures all OAuth endpoints, JWKS URL, supported scopes, etc.

Rate Limiting

API endpoints are rate limited to ensure service stability:

  • OAuth endpoints: 10 requests per minute per IP
  • Token validation: 60 requests per minute per token
  • Admin API: 30 requests per minute per admin session
  • Public registration: 5 requests per hour per IP
// Rate limit headers in response
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1627399287  // Unix timestamp

// 429 Too Many Requests response
{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Retry after 60 seconds.",
  "retry_after": 60
}

Related Documentation

Support