API Authentication Guide

API Authentication Guide

Learn how to securely authenticate with the AtoShip API using API keys.

Overview

Authentication Method: AtoShip uses API key authentication for all API requests. Each request must include your API key in the header.

Getting Your API Key

Step-by-Step:

1. Log in to AtoShip
2. Go to Settings → API
3. Click "Generate API Key"
4. Copy and save securely
5. Key shown only once

API Key Types

Key Levels:

Authentication Header

Required Header:

Authorization: Bearer YOUR_API_KEY

Example Request:

curl -X GET https://api.atoship.com/v1/rates \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

API Key Format

Key Structure:

sk_live_xxxxxxxxxxxxxxxxxxxx (Live key)
sk_test_xxxxxxxxxxxxxxxxxxxx (Test key)

Code Examples

JavaScript:

const response = await fetch('https://api.atoship.com/v1/rates', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  }
});

Python:

import requests

headers = {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
}
response = requests.get(
    'https://api.atoship.com/v1/rates',
    headers=headers
)

PHP:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.atoship.com/v1/rates');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sk_live_abc123...',
    'Content-Type: application/json'
]);
$response = curl_exec($ch);

Security Best Practices

Protect Your Keys:

1. Never expose in client code
2. Use environment variables
3. Rotate keys periodically
4. Use test keys for development
5. Monitor API usage

Environment Variables

Store Securely:

# .env file (never commit!)
ATOSHIP_API_KEY=sk_live_abc123...

Access in Code:

const apiKey = process.env.ATOSHIP_API_KEY;

Key Rotation

When to Rotate:

• Suspected compromise
• Employee departure
• Regular security policy
• After security audit

How to Rotate:

1. Generate new key
2. Update applications
3. Test with new key
4. Revoke old key

Rate Limiting

Default Limits:

Error Responses

Authentication Errors:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "status": 401
  }
}

Common Errors:

Multiple API Keys

Use Cases:

• Different environments
• Different services
• Team members
• External integrators

Key Permissions

Scope Control:

• Full access (default)
• Read-only
• Specific endpoints
• Custom scopes

IP Restrictions

Optional Security:

• Whitelist IPs
• Block unknown sources
• Audit access logs

Monitoring Usage

Track Activity:

• API call count
• Endpoint usage
• Error rates
• Response times

Revoking Keys

When Needed:

1. Settings → API
2. Find the key
3. Click "Revoke"
4. Confirm action

Troubleshooting

Auth Issues:

1. Verify key format
2. Check header spelling
3. Ensure Bearer prefix
4. Verify key is active
5. Check rate limits

Test Mode

Development Setup:

• Use test API key
• No real charges
• Simulated responses
• Safe to experiment