Skip to main content

​
Overview

The Satsuma API uses API key authentication for secure access to all endpoints. This guide covers how to obtain, configure, and use your API keys properly.

​
API Key Management

​
Getting Your API Key

1

Create Account

Sign up at dashboard.satsuma.ai for your developer account
2

Generate API Key

Navigate to the API Keys section and click “Generate New Key”
3

Configure Key

Configure your API key settings as needed
4

Copy and Store

Copy your API key and store it securely - it won’t be shown again
API keys provide access to your account and should be treated like passwords. Never commit them to version control or expose them in client-side code.

​
Authentication Methods

​
Header-based Authentication

Include your API key in the Authorization header for all requests: 
curl -X GET 'https://api.satsuma.ai/product?latitude=37.7749&longitude=-122.4194' \
  -H 'Authorization: sk_live_abcd1234567890'

​
Environment Configuration

​
Development vs Production

Use different API keys for development and production environments: 
# Development
SATSUMA_API_KEY=sk_test_1234567890abcdef
SATSUMA_BASE_URL=https://api-staging.satsuma.ai

# Production  
SATSUMA_API_KEY=sk_live_abcd1234567890
SATSUMA_BASE_URL=https://api.satsuma.ai

​
SDK Authentication

​
JavaScript/Node.js SDK

import { SatsumaClient } from '@satsuma/sdk';

const client = new SatsumaClient({
  apiKey: process.env.SATSUMA_API_KEY,
  environment: 'production' // or 'staging'
});

// SDK handles authentication automatically
const products = await client.products.search({
  query: 'coffee',
  latitude: 37.7749,
  longitude: -122.4194,
  distance: '10mi'
});

​
Python SDK

from satsuma import Client

client = Client(
    api_key=os.environ['SATSUMA_API_KEY'],
    environment='production'  # or 'staging'
)

# SDK handles authentication automatically
products = client.products.search(
    query='coffee',
    latitude=37.7749,
    longitude=-122.4194,
    distance='10mi'
)

​
Security Best Practices

​
API Key Storage

Store API keys in environment variables, never in code:
export SATSUMA_API_KEY=sk_live_abcd1234567890
Use services like AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault:
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();

const secret = await secretsManager.getSecretValue({
  SecretId: 'satsuma-api-key'
}).promise();
If using config files, ensure they’re not committed to version control:
# .gitignore
config/secrets.json
.env
*.key

​
Network Security

  • Always use HTTPS endpoints (http:// requests will be rejected)
  • Implement proper certificate validation
  • Use connection timeouts and retry logic
  • Consider IP allowlisting for production environments

​
Key Rotation

1

Generate New Key

Create a new API key with the same settings as your current key
2

Update Applications

Deploy the new key to all applications and services
3

Verify Operation

Confirm all services are working with the new key
4

Revoke Old Key

Delete the old API key from your dashboard

​
Error Handling

​
Authentication Errors

Handle authentication failures gracefully: 
try {
  const response = await fetch('https://api.satsuma.ai/product?latitude=37.7749&longitude=-122.4194', {
    headers: { 'Authentication': apiKey }
  });

  if (response.status === 401) {
    throw new Error('Invalid or expired API key');
  }
  
  if (response.status === 403) {
    throw new Error('Insufficient permissions for this operation');
  }

} catch (error) {
  console.error('Authentication failed:', error.message);
}

​
Rate Limiting

Implement proper backoff when hitting rate limits: 
async function makeRequestWithBackoff(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

​
Testing Authentication

​
API Key Validation

Test your API key setup with a simple request: 
curl -X GET 'https://api.satsuma.ai/product?latitude=37.7749&longitude=-122.4194' \
  -H 'Authorization: your-api-key-here' \
  -w "Status: %{http_code}\n"

​
Endpoint Testing

Verify your API key works with different endpoints: 
const testEndpoints = async (apiKey) => {
  const tests = [
    { endpoint: '/product?latitude=37.7749&longitude=-122.4194', description: 'Product search' },
    { endpoint: '/cart', method: 'POST', description: 'Cart management' },
    { endpoint: '/order', method: 'POST', description: 'Order placement' }
  ];

  for (const test of tests) {
    try {
      const response = await fetch(`https://api.satsuma.ai${test.endpoint}`, {
        method: test.method || 'GET',
        headers: { 'Authorization': apiKey }
      });
      
      console.log(`${test.description}: ${response.status === 403 ? 'Access Denied' : 'OK'}`);
    } catch (error) {
      console.log(`${test.description}: ERROR - ${error.message}`);
    }
  }
};

​
Need Help?

If you’re having trouble with authentication:
  • Check your API key format and ensure it’s not truncated
  • Verify you’re using the correct environment (staging vs production)
  • Confirm your key has the required permissions for your use case
  • Review the Error Handling guide for common issues
  • Contact support@satsuma.ai for assistance
⌘I