Skip to main content

ADR-003: OAuth Authentication Strategy

Status: Accepted Date: December 17, 2025 Deciders: CODITECT Architecture Team

Context​

Zoom APIs require OAuth 2.0 authentication. We need to decide on authentication patterns that support both individual users and organizational deployments.

Decision​

We will support two authentication modes:

1. User OAuth (Default)​

  • Standard OAuth 2.0 authorization code flow
  • User grants access to their Zoom account
  • Tokens stored securely per-user
  • Best for: Individual users, small teams

2. Server-to-Server OAuth (Enterprise)​

  • App authenticates at account level
  • No user interaction required
  • Single credential manages all users in account
  • Best for: Automation, enterprise deployments
  • Requires: Zoom Admin privileges

Authentication Flow​

User OAuth:
User → Consent Screen → Auth Code → Token Exchange → Access Token

Server-to-Server OAuth:
App → Account Credentials Grant → Access Token (auto-refresh)

Token Management​

@dataclass
class ZoomTokenStorage:
    access_token: str
    refresh_token: str  # Only for User OAuth
    expires_at: datetime
    token_type: str
    scope: str

    def needs_refresh(self) -> bool:
        return datetime.utcnow() >= self.expires_at - timedelta(minutes=5)

Security Requirements​

  1. Token Encryption: AES-256 at rest
  2. Refresh Token Protection: Stored separately from access tokens
  3. Scope Minimization: Request only required scopes
  4. Token Rotation: Access tokens expire after 1 hour

OAuth App Types​

App TypeUse CaseAuth Method
OAuth AppUser-level accessAuthorization Code
Server-to-ServerAccount-level automationAccount Credentials

Consequences​

Positive​

  • Supports both individual and enterprise use cases
  • Standard OAuth flow is well-understood
  • Server-to-Server enables full automation
  • No need to manage user consent for automation

Negative​

  • Server-to-Server requires Zoom Admin setup
  • Token management adds complexity
  • Must handle token refresh failures gracefully
  • User OAuth requires redirect URI infrastructure

Required Scopes​

# Minimum required (User OAuth)
meeting:read        # Read meeting details
meeting:write       # Create/update meetings
user:read           # Read user info

# Full functionality
recording:read      # Access cloud recordings
report:read:admin   # Usage reports (admin only)

# Server-to-Server scopes (account-level)
meeting:read:admin
meeting:write:admin
recording:read:admin
user:read:admin

References​