Advanced Authentication Patterns — OAuth 2.0, JWT, Key Rotation

Authentication Overview

The Smart Money API supports multiple authentication methods designed to accommodate different application architectures, security requirements, and organizational policies. Understanding these patterns ensures your integration is both secure and performant.

Authentication in the Smart Money API operates across three primary layers:

• API Keys — Simple bearer token authentication for development and straightforward integrations
• JWT Tokens — Stateless, cryptographically signed tokens for distributed systems and microservices
• OAuth 2.0 — Delegated authorization framework for third-party integrations and SaaS applications

Each method has distinct advantages. API keys work best for backend-to-backend communication where credential storage is controlled. JWT tokens excel in distributed architectures where no shared state is available. OAuth 2.0 provides user-delegated access for third-party applications.

API Key Authentication

API keys are the simplest authentication mechanism—they're random strings generated for your account that identify your application to the Smart Money API. Every request must include your API key either as a header or query parameter.

Header-Based API Key

The recommended approach is passing your API key in the Authorization header using the Bearer scheme:

Query Parameter API Key

For WebSocket connections or when headers cannot be modified, pass the API key as a query parameter:

API Key Characteristics

API Key Security Practices

• Environment Variables — Store keys in .env files (not committed to version control) and load at runtime
• Vault Systems — Use HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault in production
• Separate Keys — Maintain separate test and live keys; rotate test keys frequently
• Minimal Scope — Create separate keys for different integrations when possible
• Audit Logging — Log all API key creation and usage events

Bearer Token Pattern

Bearer tokens extend the simple API key concept by adding context, expiration, and refresh mechanisms. They're ideal for applications that need programmatic credential management.

Obtaining Bearer Tokens

Exchange your API key and secret for a bearer token valid for 24 hours:

Token Response Format

The endpoint returns a bearer token with metadata:

Using Bearer Tokens

Include the token in the Authorization header for all subsequent requests:

Token Refresh Flow

When a token approaches expiration, use the refresh token to obtain a new one without requiring your API secret:

OAuth 2.0 Implementation

OAuth 2.0 enables users to grant applications access to their Smart Money API accounts without sharing credentials. This is essential for SaaS platforms, third-party integrations, and multi-tenant applications.

OAuth 2.0 Authorization Code Flow

The standard flow for web applications:

1. User Initiates Login — User clicks "Connect with Smart Money API"
2. Redirect to Authorization Server — Your app redirects user to Smart Money's authorization endpoint
3. User Grants Permission — User reviews requested scopes and grants access
4. Authorization Code Returned — User redirected back with authorization code
5. Exchange Code for Token — Backend exchanges code for access token (code never exposed to frontend)
6. Store Token — Store refresh token securely; use access token for API calls

Step 1: Redirect User to Authorization Endpoint

Step 2: Handle Callback and Exchange Code

OAuth Scopes

Request only the scopes your application needs. Smart Money API defines these scopes:

JWT Token Management

JWT (JSON Web Tokens) provide stateless authentication—the server doesn't need to store session data. Smart Money API uses RS256 (RSA Signature with SHA-256) for token signing, allowing verification without contacting the API.

JWT Structure

JWT tokens consist of three parts separated by dots:

JWT Header

The header identifies the algorithm and token type:

JWT Payload Claims

The payload contains claims (statements about the user/app):

Verifying JWT Signatures

Download Smart Money's public key and verify tokens before accepting them:

Key Rotation Strategy

Regular key rotation is critical for maintaining security. Even with perfect security practices, assume keys can be compromised and implement systematic rotation.

Rotation Frequency

Smart Money recommends different rotation schedules based on key type and usage:

Zero-Downtime Rotation Process

Rotate keys without interrupting service:

1. Generate New Key — Create new API key through dashboard or API
2. Deploy New Key — Update application secrets in staging, test thoroughly
3. Gradual Rollout — Deploy to 10% of servers, monitor for errors
4. Full Rollout — Deploy to remaining servers
5. Verify Traffic — Confirm all requests use new key
6. Deactivate Old Key — Mark old key as inactive but don't delete immediately
7. Delete Old Key — After 48 hours with no errors, permanently delete

Emergency Key Rotation

If you suspect a key is compromised:

Automated Rotation in Kubernetes

Use Kubernetes Secrets and operators for automatic rotation:

Multi-Factor Authentication (MFA)

For accounts accessing production data, MFA provides an additional security layer by requiring a second factor beyond just credentials.

MFA Methods Supported

• TOTP (Time-based One-Time Password) — Apps like Google Authenticator, Authy
• WebAuthn/FIDO2 — Hardware security keys, biometrics
• SMS One-Time Codes — Less secure but universally supported
• Email Confirmation — Confirmation codes sent to registered email

Enabling TOTP for Account Access

MFA During API Operations

Some operations may require MFA confirmation even after authentication:

Security Best Practices

Authentication is only as strong as its implementation. Follow these practices to maintain security:

Secrets Management

• Never commit secrets to version control — Use .env files with .gitignore
• Use environment variables — Load from secure secret management systems
• Scan repositories — Use tools like TruffleHog, detect-secrets to find exposed keys
• Audit access logs — Monitor who accessed secrets and when

Transport Security

• Always use HTTPS — Never send credentials over unencrypted connections
• Verify SSL certificates — Don't disable certificate validation in production
• Use certificate pinning — For mobile apps, prevent MITM attacks
• Enforce TLS 1.2+ — Disable older protocols

Credential Handling

• Hash secrets — Store bcrypt or Argon2 hashes, never plaintext
• Minimize lifetime — Keep credentials in memory only as long as needed
• Clear sensitive data — Explicitly overwrite credentials after use
• Use secure libraries — Don't implement cryptography yourself

Logging and Monitoring

• Never log credentials — Redact keys in logs, use log masking
• Log authentication events — Track successful and failed login attempts
• Monitor for anomalies — Alert on unusual access patterns
• Audit key usage — Track which keys accessed what data

Enterprise Authentication Patterns

Large organizations often require additional security controls and compliance capabilities.

SAML 2.0 Integration

For enterprise customers, Smart Money API supports SAML 2.0 integration with your organization's identity provider (Okta, Azure AD, etc.):

• Single Sign-On (SSO) — Users authenticate through your corporate IdP
• Automatic provisioning — Create/disable accounts based on group membership
• Enforcement — Require SAML for all user access

IP Whitelisting

Restrict API access to specific IP addresses or CIDR ranges:

Audit Logging and Compliance

Enterprise plans include comprehensive audit logs for compliance:

Troubleshooting Authentication Issues

Invalid API Key Error

Problem: Receiving "401 Unauthorized - Invalid API Key"

Solutions:

• Verify key format (should start with sk_test_ or sk_live_)
• Check for trailing/leading whitespace in key
• Confirm key hasn't been deactivated or rotated
• Verify you're using the correct environment (test key for test, live for production)
• Check API key permissions match endpoint requirements

Token Expired Error

Problem: Bearer token expired, requests failing

Solutions:

• Use refresh token to obtain new access token
• Implement automatic token refresh 5 minutes before expiration
• Store refresh token securely (not in localStorage for SPAs)
• Handle 401 responses by attempting refresh token flow

CORS/Preflight Errors

Problem: Browser blocking requests with CORS error

Solutions:

• API calls from browsers must come from whitelisted origins
• Add your domain via dashboard: Settings → CORS Origins
• Browser sends OPTIONS preflight request automatically
• For development, use localhost:3000 or similar

MFA Challenge Not Completing

Problem: Operations requiring MFA fail even with correct code

Solutions:

• Ensure server clock is synchronized (TOTP relies on time)
• Code is valid only for 30 seconds, generate new one
• Use backup codes if authenticator app is unavailable
• Account recovery available via registered email