API Authentication & Security

Secure authentication is critical for protecting your account and API keys. Smart Money API supports multiple authentication methods: API Key authentication, JWT tokens, and OAuth. This guide covers implementation details, security best practices, and troubleshooting common authentication issues.

Authentication Guide

API Key Authentication
JWT Token Flow
OAuth Integration
Rate Limit Handling
Error Response Format
Security Best Practices
Authentication Troubleshooting
Complete Examples

API Key Authentication

API Key authentication is the simplest method, ideal for server-to-server communication. Include your API key in the X-API-Key header with every request.

API Key method characteristics:

Simplest implementation - single header value
No token refresh required
Suitable for backend services with secure key storage
Best for fixed-frequency data polling
IP restriction recommended for security

        CURL
      

# Basic API key authentication
curl -X GET "https://api.smartmoneyapi.com/v1/onchain/whale-activity-24h" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

# Response
{
  "status": "success",
  "movements": [
    {
      "address": "1A1z7agoat...",
      "btc_amount": 125.5,
      "direction": "to_exchange",
      "timestamp": "2026-03-21T14:30:00Z"
    }
  ]
}
      

JWT Token Flow

JWT (JSON Web Token) authentication is suitable for applications requiring user authorization. Exchange credentials for a time-limited JWT token that's included in request headers.

JWT flow process:

Send login credentials to the authentication endpoint
Receive JWT token (expires in 24 hours)
Include token in Authorization header: "Bearer token_here"
Refresh token before expiration using refresh endpoint

        PYTHON
      

import requests
import json
from datetime import datetime, timedelta

class SmartMoneyJWTAuth:
    def __init__(self, email, password):
        self.base_url = 'https://api.smartmoneyapi.com/v1'
        self.token = None
        self.token_expiry = None
        self.email = email
        self.password = password
        self.authenticate()

    def authenticate(self):
        """Login and get JWT token"""
        response = requests.post(
            f'{self.base_url}/auth/login',
            json={
                'email': self.email,
                'password': self.password
            }
        )
        data = response.json()
        self.token = data['access_token']
        self.token_expiry = datetime.now() + timedelta(hours=24)
        print(f"Authenticated. Token expires: {self.token_expiry}")

    def refresh_token(self):
        """Refresh JWT token"""
        response = requests.post(
            f'{self.base_url}/auth/refresh',
            headers={'Authorization': f'Bearer {self.token}'}
        )
        data = response.json()
        self.token = data['access_token']
        self.token_expiry = datetime.now() + timedelta(hours=24)

    def get_headers(self):
        """Get authorization headers"""
        if datetime.now() > self.token_expiry - timedelta(minutes=5):
            self.refresh_token()
        return {
            'Authorization': f'Bearer {self.token}',
            'Content-Type': 'application/json'
        }

    def request(self, method, endpoint, **kwargs):
        """Make authenticated request"""
        headers = self.get_headers()
        url = f'{self.base_url}{endpoint}'
        return requests.request(method, url, headers=headers, **kwargs)

# Usage
auth = SmartMoneyJWTAuth('user@example.com', 'password')
response = auth.request('GET', '/onchain/whale-activity-24h')
print(response.json())
      

OAuth Integration

OAuth is recommended for third-party applications accessing user data with explicit permission. Implements standard OAuth 2.0 flow with authorization codes and refresh tokens.

OAuth enables secure delegation of permissions without sharing passwords. Users grant your application specific scopes of access (read-only, write, etc.) that can be revoked anytime.

Rate Limit Handling

All API tiers have rate limits. Monitor rate limit headers to avoid 429 (Too Many Requests) responses.

Rate Limits by Tier

Free: 200 requests/day, 1 concurrent connection
Trader: 3,000 requests/day, 5 concurrent connections
Pro: 15,000 requests/day, 20 concurrent connections, batch operations

Security Best Practices

Critical: Never commit API keys to version control. Use environment variables, secret management systems (Vault, AWS Secrets Manager), or .env files (git-ignored).

Essential security practices:

Rotate API keys quarterly and after suspected compromises
Restrict API keys to specific IP addresses when possible
Use HTTPS only - never send API keys over unencrypted connections
Monitor API usage in dashboard for anomalies
Implement request signing for extra security on sensitive operations
Create separate keys for development and production
Immediately revoke keys if exposed in logs or code

Secure Your Integration

Review our security checklist and implement best practices in your integration. Start with API key setup and progress to OAuth for production applications.

View Full Security Guide