Authentication

The Flash Americas API uses API key authentication to secure access to all endpoints. This guide explains how to obtain, configure, and use API keys effectively.

API Key Overview

API keys provide a secure way to authenticate your applications with the Flash Americas API. Each API key:

  • Uniquely identifies your application or integration
  • Controls access to specific API endpoints and features
  • Tracks usage for billing and rate limiting purposes
  • Enables monitoring of API calls and performance metrics

Getting Your API Key

Production API Keys

To obtain a production API key:

  1. Contact Sales: Reach out to our sales team at sales@flashamericas.com
  2. Complete Onboarding: Provide business information and integration requirements
  3. Receive Credentials: Get your production API key and account configuration
  4. Test Integration: Verify your setup with our support team

Sandbox API Keys

For development and testing, request a sandbox API key:

  1. Contact Support: Email support@flashamericas.com
  2. Provide Details: Include your name, company, and intended use case
  3. Receive Test Key: Get sandbox credentials for development
  4. Start Building: Begin integration with test data

Using Your API Key

Basic Authentication

Include your API key in the Authorization header of every request:

curl -X GET "https://ship.flashamericas.com/api/v1/health" \
-H "Authorization: Bearer YOUR_API_KEY"

Environment Configuration

Store your API key securely in environment variables:

.envbash
# Production
FLASH_AMERICAS_API_KEY=live_abc123def456...

# Sandbox  
FLASH_AMERICAS_API_KEY=test_xyz789uvw012...

Code Examples

Node.js/TypeScript

api-client.tstypescript
import axios from 'axios';

const apiClient = axios.create({
baseURL: 'https://ship.flashamericas.com/api/v1',
headers: {
  'Authorization': `Bearer ${process.env.FLASH_AMERICAS_API_KEY}`,
  'Content-Type': 'application/json'
}
});

// Example: Get shipping quotes
async function getQuotes(quoteRequest: QuoteRequest) {
try {
  const response = await apiClient.post('/quote', {
    ...quoteRequest,
    returnJson: true
  });
  return response.data;
} catch (error) {
  console.error('API Error:', error.response?.data);
  throw error;
}
}

Python

api_client.pypython
import os
import requests
from typing import Dict, Any

class FlashAmericasAPI:
  def __init__(self):
      self.base_url = "https://ship.flashamericas.com/api/v1"
      self.api_key = os.getenv("FLASH_AMERICAS_API_KEY")
      self.headers = {
          "Authorization": f"Bearer {self.api_key}",
          "Content-Type": "application/json"
      }
  
  def get_quotes(self, quote_request: Dict[str, Any]) -> Dict[str, Any]:
      """Get shipping quotes from the API"""
      quote_request['returnJson'] = True
      response = requests.post(
          f"{self.base_url}/quote",
          json=quote_request,
          headers=self.headers
      )
      response.raise_for_status()
      return response.json()

# Usage
api = FlashAmericasAPI()
quotes = api.get_quotes({
  "originAddress": {"city": "Dallas", "state": "TX"},
  "destinationAddress": {"city": "Houston", "state": "TX"},
  "cargo": [{"weight": 25, "length": 18, "width": 12, "height": 10}]
})

PHP

ApiClient.phpphp
<?php

class FlashAmericasAPI 
{
  private $baseUrl = 'https://ship.flashamericas.com/api/v1';
  private $apiKey;
  
  public function __construct() 
  {
      $this->apiKey = getenv('FLASH_AMERICAS_API_KEY');
  }
  
  public function getQuotes(array $quoteRequest): array 
  {
      $ch = curl_init();
      
      curl_setopt_array($ch, [
          CURLOPT_URL => $this->baseUrl . '/quote',
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_POST => true,
          CURLOPT_POSTFIELDS => json_encode($quoteRequest),
          CURLOPT_HTTPHEADER => [
              'Authorization: Bearer ' . $this->apiKey,
              'Content-Type: application/json',
              'Accept: application/json'
          ]
      ]);
      
      $response = curl_exec($ch);
      $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);
      
      if ($httpCode !== 200) {
          throw new Exception("API Error: HTTP $httpCode");
      }
      
      return json_decode($response, true);
  }
}

// Usage
$api = new FlashAmericasAPI();
$quotes = $api->getQuotes([
  'originAddress' => ['city' => 'Dallas', 'state' => 'TX'],
  'destinationAddress' => ['city' => 'Houston', 'state' => 'TX'],
  'cargo' => [['weight' => 25, 'length' => 18, 'width' => 12, 'height' => 10]]
]);

API Key Security

Best Practices

✅ DO:

  • Store API keys in environment variables
  • Use different keys for development and production
  • Implement proper error handling for authentication failures
  • Monitor API key usage and performance
  • Rotate keys periodically for enhanced security

❌ DON'T:

  • Hardcode API keys in source code
  • Commit API keys to version control
  • Share API keys in public forums or documentation
  • Use production keys in development environments
  • Ignore authentication error responses

Secure Storage

Environment Variables

# Set environment variable
export FLASH_AMERICAS_API_KEY="your_api_key_here"

# Or in your deployment configuration
FLASH_AMERICAS_API_KEY=your_api_key_here

Configuration Files

config.jsonjson
{
"api": {
  "baseUrl": "https://ship.flashamericas.com/api/v1",
  "keyEnvVar": "FLASH_AMERICAS_API_KEY"
}
}

Key Rotation

Periodically rotate your API keys for enhanced security:

  1. Request New Key: Contact support for a new API key
  2. Update Applications: Deploy new key to all environments
  3. Verify Functionality: Test all integrations with new key
  4. Revoke Old Key: Disable the previous key after successful transition

Authentication Errors

Common Error Responses

Missing API Key

{
"success": false,
"error": {
  "code": "AUTHENTICATION_REQUIRED",
  "message": "API key is required"
}
}

Invalid API Key

{
"success": false,
"error": {
  "code": "AUTHENTICATION_ERROR", 
  "message": "Invalid API key"
}
}

Expired API Key

{
"success": false,
"error": {
  "code": "AUTHENTICATION_EXPIRED",
  "message": "API key has expired"
}
}

Error Handling

Implement robust error handling for authentication issues:

async function apiRequest(endpoint: string, data?: any) {
try {
  const response = await apiClient.post(endpoint, data);
  return response.data;
} catch (error) {
  if (error.response?.status === 401) {
    // Handle authentication error
    throw new Error('Authentication failed. Please check your API key.');
  } else if (error.response?.status === 403) {
    // Handle authorization error  
    throw new Error('Access denied. Your API key may not have the required permissions.');
  }
  throw error;
}
}

API Key Permissions

Different API keys may have varying levels of access:

Read-Only Keys

  • Get quotes and rates
  • Retrieve shipment information
  • Access tracking data
  • View documents

Full Access Keys

  • All read-only permissions
  • Create and book shipments
  • Generate shipping labels
  • Manage webhooks
  • Access billing information

Admin Keys

  • All full access permissions
  • Manage account settings
  • Create additional API keys
  • Access analytics and reporting

Testing Authentication

Health Check Endpoint

Test your API key with the health check endpoint:

curl -X GET "https://ship.flashamericas.com/api/v1/health" \
-H "Authorization: Bearer YOUR_API_KEY"

Expected response:

{
"success": true,
"data": {
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-01-15T10:30:00Z"
}
}

Account Information

Verify your API key permissions:

curl -X GET "https://ship.flashamericas.com/api/v1/help" \
-H "Authorization: Bearer YOUR_API_KEY"

Rate Limiting with Authentication

API keys are subject to rate limiting based on your plan:

  • Sandbox: 100 requests per minute
  • Production Basic: 1,000 requests per minute
  • Production Premium: 5,000 requests per minute
  • Enterprise: Custom limits

Monitor rate limit headers in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Need Help?

If you encounter authentication issues:

Next Steps

Once you have authentication working:

  1. Quick Start Guide - Make your first API call
  2. Rate Limiting - Understand usage limits
  3. API Reference - Explore all available endpoints
  4. Error Handling - Implement robust error handling