OAuth Administration

Token Status Explained

• Connected: Token is valid and actively working. The HubSpot integration can make API calls successfully.
• Expired: The access token has passed its expiration time (typically 6 hours). The token can no longer make API calls but can be refreshed using the stored refresh token.
• Disconnected: No token exists or it has been revoked. The user must reconnect through the OAuth flow to restore access.

Refresh Token

What it does: Exchanges the current refresh token for a new access token and refresh token pair.

When to use: When a token shows as "expired" but you need to restore API access without asking the user to re-authenticate.

Consequences:

• Extends access for another 6 hours without user interaction
• Previous refresh token is invalidated (HubSpot rotates refresh tokens)
• If refresh fails, the user must reconnect manually through OAuth

Revoke Token

What it does: Permanently removes the OAuth token from the database and invalidates it with HubSpot.

When to use: When a customer cancels their subscription, requests data deletion, or you detect suspicious activity.

Consequences:

• Immediate disconnection: All API access stops immediately
• Data sync stops: Any background processes relying on this token will fail
• User must re-authorize: The user must go through the complete OAuth flow again to restore access
• Cannot be undone: There is no way to restore a revoked token

WARNING: Only revoke tokens when absolutely necessary. This action cannot be undone and will interrupt all integrations.

Best Practices

• Monitor token expiration and set up automatic refresh mechanisms
• Log all refresh and revoke actions for audit purposes
• Notify users before revoking tokens (except in security incidents)
• Keep refresh tokens secure - they provide long-term access

User Status Overview

• Hub ID: Unique identifier for the HubSpot portal (account). This never changes.
• Connected Date: When the user first authorized your app through OAuth.
• Plan: Current subscription tier (Free, Starter, Professional, Enterprise).
• Status: Active (has valid tokens) or Inactive (no tokens or expired).

Disconnect User

What it does: Removes all OAuth tokens and marks the installation as disconnected.

When to use:

• User requests account deletion or data removal
• Subscription cancellation or non-payment
• Security breach or unauthorized access detected
• Violating terms of service

Consequences:

• Complete access termination: All API calls stop immediately
• Data sync halts: No more data updates from HubSpot
• User-facing features break: Any features relying on HubSpot data will fail
• Data retained: User data remains in database unless manually deleted
• Reconnection possible: User can re-authorize to restore access

WARNING: Disconnection is immediate and will disrupt the user's workflow. Notify them first unless it's a security issue.

View Details

Opens detailed view showing:

• Complete token information and expiration times
• OAuth scopes granted by the user
• Installation history and app versions
• Usage statistics and API call counts
• Recent activity and error logs

Why Multiple Apps?

You might need multiple HubSpot app configurations for:

• Development vs Production: Separate apps for testing and live environments
• Different Products: Each product line may need its own OAuth app
• Regional Deployments: Apps for different geographic regions
• A/B Testing: Testing new features with a subset of users

Add New App

Required Information:

• Client ID: From HubSpot Developer Portal (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
• Client Secret: Confidential key from HubSpot - keep secure!
• Redirect URI: Must match exactly what's configured in HubSpot (e.g., https://oauth.test.pdl.no/oauth/callback)
• Scopes: Space-separated list of permissions (e.g., "crm.objects.contacts.read crm.objects.companies.write")

Important: The Redirect URI in HubSpot must EXACTLY match what you enter here, including protocol (https://) and path.

Edit App

Safe to change:

• Label (internal name for your reference)
• Description
• Environment tag (dev/staging/production)

Requires caution:

• Scopes: Adding scopes is safe. Removing scopes may break existing features.
• Redirect URI: Must match HubSpot configuration or OAuth will fail.

Cannot change:

• Client ID: Tied to the HubSpot app. Delete and recreate if you need a different app.
• Client Secret: For security, secrets cannot be updated. Rotate in HubSpot and create new app entry.

Delete App

Consequences:

• All users using this app will lose access
• Existing tokens remain in database but cannot be refreshed
• OAuth flow will fail for new installations
• Action cannot be undone - you'll need to re-add the app with all details

DANGER: Only delete apps that are no longer in use or during decommissioning. Check "Installations" count before deleting.

Pricing Types

• Free: No charge, typically for trial or basic tier with limited features
• One-time: Single payment during registration or upgrade
• Recurring: Monthly or annual subscription charges
• Usage-based: Pay-per-use pricing (API calls, contacts synced, etc.)
• Hybrid: Combination of recurring base fee + usage charges

Add Pricing Rule

Configuration Options:

• Plan Code: Unique identifier (e.g., "starter", "pro", "enterprise")
• App Assignment: Apply to specific app or all apps (global)
• Price & Currency: Amount in specified currency (USD, EUR, NOK, etc.)
• Features: List of included features/limits (e.g., "1000 contacts, 5 users")
• Usage Limits: API rate limits, storage quotas, concurrent connections

Best Practice: Start with a free tier to lower adoption barriers, then offer paid upgrades.

Edit Pricing

Safe to change (affects new users only):

• Feature descriptions and marketing copy
• Adding new features to existing plans

Requires migration plan:

• Price changes: Existing subscribers keep old price until renewal (grandfather clause)
• Removing features: Must notify users and provide grace period
• Usage limit reductions: Inform affected users before enforcement

Recommendation: Create a new plan version (e.g., "pro_v2") instead of modifying active plans with many subscribers.

Delete Pricing Model

Prerequisites:

• No active subscribers on this plan
• Alternative plan available for migration
• All pending invoices settled

Consequences:

• Plan no longer available for new signups
• Historical records retained for accounting
• Cannot be restored - create new plan if needed

WARNING: Attempting to delete a plan with active users will fail. Migrate users first.

Status Management

• Active: Available for new signups and renewals
• Inactive/Hidden: Not shown to new users, but existing subscribers keep access
• Deprecated: No new signups, existing users encouraged to migrate
• Archived: No users remaining, kept for historical records only

Security & Rate Limiting

Why rate limiting matters:

• Prevents brute-force attacks on OAuth endpoints
• Protects against denial-of-service (DoS) attempts
• Ensures fair resource usage across all users

Recommended settings:

• Production: 10 requests per 1-minute window
• Development: 30 requests per 5-minute window (more lenient for testing)

Too restrictive: May block legitimate retry attempts. Too loose: Vulnerable to abuse.

Logging Configuration

Verbose Logging:

• Advantages: Detailed troubleshooting, full request/response visibility, easier debugging
• Disadvantages: Increased disk usage, slower performance, potential sensitive data exposure

Log Level Guide:

• ERROR: Critical issues requiring immediate attention
• WARN: Potential problems, degraded functionality
• INFO: Important events (OAuth success, user registration)
• DEBUG: Detailed diagnostic information (enable temporarily)

Best Practice: Use INFO for production, DEBUG only when troubleshooting specific issues.

Backup & Disaster Recovery

Automated Backups:

• Daily schedule: Runs at 01:00 (1 AM) server time
• Retention: Keeps last 30 backups by default
• Contents: Full database snapshot (tenants, tokens, settings, logs)

Manual Backup:

• Use before major configuration changes
• Before bulk user operations (migrations, deletions)
• Prior to software updates

Recovery Time: Database restore takes 1-5 minutes depending on size. Service will be offline during restore.

Integration Testing

What gets tested:

• OAuth flow initiation and callback handling
• Token exchange and refresh mechanisms
• HubSpot API connectivity
• Database schema validation
• Rate limiting enforcement

When to run tests:

• After changing OAuth credentials or configuration
• Before deploying to production
• When troubleshooting connection issues
• Weekly as part of maintenance routine

Note: Tests use real HubSpot API endpoints but in test mode (no actual data changes).

Maintenance Actions

Clear Rate Limit Cache:

• Resets all rate limit counters immediately
• Use when legitimate users are blocked
• Security risk: Temporarily removes protection against abuse

Reload Configuration:

• Re-reads .env file without restarting service
• Applies new settings (port, URL, tokens)
• Zero downtime - users stay connected

Server Restart:

• Immediate impact: All active OAuth flows interrupted
• User experience: Users mid-authentication must start over
• Downtime: 3-5 seconds typically
• When necessary: After code updates, dependency changes, or severe errors

CRITICAL: Restart during low-traffic periods. Notify users if possible. Use "Reload Config" instead when applicable.