Authentication

AS2aaS uses API key authentication for all platform access. API keys provide secure, programmatic access to your tenant's resources with configurable permissions and rate limiting.

API Key Types

The platform supports two distinct API key environments:

Test Environment Keys

pk_test_4eC39HqLyjWDarjtT1zdp7dc

Test keys provide access to a sandboxed environment for development and testing. Messages sent using test keys are processed in isolation and do not affect production trading partners.

Production Environment Keys

pk_live_4eC39HqLyjWDarjtT1zdp7dc

Production keys enable access to live AS2 messaging capabilities. Messages sent using production keys are transmitted to actual trading partners and may incur charges.

Request Authentication

Include your API key in the Authorization header using the Bearer token format:

curl -X GET https://api.as2aas.com/v1/partners \
  -H "Authorization: Bearer pk_test_your_api_key_here"

Permission Scopes

API keys can be configured with specific permission scopes to limit access:

Scope-based Access Control

// Example API key configurations
{
  "read_only_key": ["read"],
  "integration_key": ["read", "write"], 
  "admin_key": ["read", "write", "delete", "admin"]
}

Rate Limiting

Rate Limit Headers

The platform includes rate limit information in response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299  
X-RateLimit-Reset: 1640995200

Rate Limit Exceeded Response

When rate limits are exceeded, the API returns a 429 Too Many Requests status:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded", 
    "message": "API rate limit exceeded. Please wait before making additional requests.",
    "retry_after": 60
  }
}

Security Configuration

IP Address Restrictions

Restrict API key usage to specific IP addresses or CIDR ranges:

curl -X PATCH https://api.as2aas.com/v1/api-keys/key_123 \
  -H "Authorization: Bearer pk_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_allowlist": ["203.0.113.1", "198.51.100.0/24"]
  }'

Key Expiration

Configure automatic key expiration for enhanced security:

curl -X PATCH https://api.as2aas.com/v1/api-keys/key_123 \
  -H "Authorization: Bearer pk_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Best Practices

Secure Key Storage

Store API keys using environment variables:

# Environment configuration
AS2AAS_API_KEY=pk_live_your_production_key
AS2AAS_TEST_KEY=pk_test_your_test_key

// Node.js implementation
const apiKey = process.env.AS2AAS_API_KEY;

# Python implementation
import os
api_key = os.environ.get('AS2AAS_API_KEY')

// PHP implementation
$apiKey = $_ENV['AS2AAS_API_KEY'];

Key Rotation

Implement regular key rotation for production environments:

1. Generate new API key with identical permissions
2. Update application configuration to use new key
3. Verify functionality with new key
4. Revoke old API key
5. Monitor for any authentication failures

Monitoring and Auditing

Monitor API key usage through the platform dashboard:

• Request volume and patterns
• Error rates and authentication failures
• Geographic distribution of requests
• Last activity timestamps

Error Responses

Invalid API Key

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Expired API Key

{
  "error": {
    "type": "authentication_error", 
    "code": "api_key_expired",
    "message": "The API key has expired and must be renewed."
  }
}

Insufficient Permissions

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "The API key does not have sufficient permissions for this operation."
  }
}

IP Address Restricted

{
  "error": {
    "type": "authorization_error",
    "code": "ip_not_allowed", 
    "message": "Requests from this IP address are not permitted for this API key."
  }
}

Implementation Examples

Basic Authentication

curl -X GET https://api.as2aas.com/v1/partners \
  -H "Authorization: Bearer pk_test_your_api_key"

With Custom Headers

curl -X POST https://api.as2aas.com/v1/messages \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg_unique_12345" \
  -d '{"partner_id": "prt_001", "payload": {...}}'

Error Handling

const response = await fetch('https://api.as2aas.com/v1/partners', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.error.message);
  
  if (error.error.code === 'rate_limit_exceeded') {
    // Implement backoff strategy
    await new Promise(resolve => setTimeout(resolve, 60000));
  }
}