Authentication Endpoints

Authentication Endpoints

The authentication system in Spartera uses API keys for secure access
to all endpoints. These endpoints allow you to manage API keys
programmatically, including creation, updating, monitoring, and
deactivation.

API Key Management

List API Keys

Get all API keys for a company with masked key values for security.

HTTP

GET /companies/{company_id}/api-keys

List API Keys Parameters

• company_id (path, required): Unique identifier for the company

List API Keys Headers

JSON

x-api-key: {your_api_key}
accept: application/json

List API Keys Response

JSON

{
  "data": [
    {
      "id": "key_12345",
      "name": "Production API Key",
      "key": "sk_****1234",
      "created_at": "2025-01-15T10:30:00Z",
      "expires_at": "2026-01-15T10:30:00Z",
      "last_used": "2025-01-20T14:22:00Z",
      "status": "active",
      "rate_limit": 1000,
      "permissions": ["read", "write"]
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 50
  }
}

Create API Key

Generate a new API key. The full key is returned only once during
creation.

HTTP

POST /companies/{company_id}/api-keys

Create API Key Parameters

• company_id (path, required): Unique identifier for the company

Create API Key Request Body

JSON

{
  "name": "New API Key",
  "expires_at": "2026-01-15T10:30:00Z",
  "rate_limit": 5000,
  "permissions": ["read", "write"],
  "description": "Key for production analytics access"
}

Create API Key Response

JSON

{
  "data": {
    "id": "key_67890",
    "name": "New API Key",
    "key": "sk_live_1234567890abcdef",
    "created_at": "2025-01-20T15:30:00Z",
    "expires_at": "2026-01-15T10:30:00Z",
    "status": "active",
    "rate_limit": 5000,
    "permissions": ["read", "write"]
  }
}

Get API Key Details

Retrieve details for a specific API key with masked key value.

HTTP

GET /companies/{company_id}/api-keys/{api_key_id}

Get API Key Details Parameters

• company_id (path, required): Unique identifier for the company
• api_key_id (path, required): Unique identifier for the API key

Get API Key Details Response

JSON

{
  "data": {
    "id": "key_12345",
    "name": "Production API Key",
    "key": "sk_****1234",
    "created_at": "2025-01-15T10:30:00Z",
    "expires_at": "2026-01-15T10:30:00Z",
    "last_used": "2025-01-20T14:22:00Z",
    "status": "active",
    "rate_limit": 1000,
    "permissions": ["read", "write"],
    "description": "Main production key"
  }
}

Update API Key

Update metadata for an existing API key, such as name, expiry, or
rate limits.

HTTP

PATCH /companies/{company_id}/api-keys/{api_key_id}

Update API Key Parameters

• company_id (path, required): Unique identifier for the company
• api_key_id (path, required): Unique identifier for the API key

Update API Key Request Body

JSON

{
  "name": "Updated API Key Name",
  "expires_at": "2027-01-15T10:30:00Z",
  "rate_limit": 2000,
  "permissions": ["read"],
  "description": "Updated description"
}

Update API Key Response

JSON

{
  "data": {
    "id": "key_12345",
    "name": "Updated API Key Name",
    "key": "sk_****1234",
    "expires_at": "2027-01-15T10:30:00Z",
    "rate_limit": 2000,
    "permissions": ["read"],
    "updated_at": "2025-01-20T16:00:00Z"
  }
}

Delete API Key

Deactivate an API key, making it unusable for future requests.

HTTP

DELETE /companies/{company_id}/api-keys/{api_key_id}

Delete API Key Parameters

• company_id (path, required): Unique identifier for the company
• api_key_id (path, required): Unique identifier for the API key

Delete API Key Response

HTTP

204 No Content

Get API Key Statistics

Retrieve usage statistics for a specific API key.

HTTP

GET /companies/{company_id}/api-keys/{api_key_id}/stats

Get API Key Statistics Parameters

• company_id (path, required): Unique identifier for the company
• api_key_id (path, required): Unique identifier for the API key

Get API Key Statistics Query Parameters

• period (optional): Time period for statistics (24h, 7d, 30d, 90d)
• start_date (optional): Start date for custom period (ISO 8601)
• end_date (optional): End date for custom period (ISO 8601)

Get API Key Statistics Response

JSON

{
  "data": {
    "api_key_id": "key_12345",
    "period": "30d",
    "total_requests": 15420,
    "successful_requests": 14890,
    "failed_requests": 530,
    "last_used": "2025-01-20T14:22:00Z",
    "first_used": "2025-01-15T10:30:00Z",
    "usage_by_endpoint": {
      "/analytics/": 8500,
      "/marketplace/": 4200,
      "/insights/": 2720
    },
    "usage_by_day": [
      {
        "date": "2025-01-20",
        "requests": 892
      },
      {
        "date": "2025-01-19",
        "requests": 756
      }
    ]
  }
}

Authentication Flow

Standard Authentication

All API requests must include a valid API key in the header:

Bash

curl --request GET \
  --url https://api.spartera.com/companies/{company_id}/api-keys \
  --header 'accept: application/json' \
  --header 'x-api-key: sk_live_1234567890abcdef'

Key Validation Process

1. Header Check: API key must be present in x-api-key header
2. Format Validation: Key must match expected format
3. Active Status: Key must be active and not expired
4. Permission Check: Key must have required permissions for endpoint
5. Rate Limit Check: Request must not exceed rate limits

Security Best Practices

API Key Management

• Secure Storage: Store API keys in environment variables or secure
  vaults
• Key Rotation: Regularly rotate API keys for enhanced security
• Minimal Permissions: Grant only necessary permissions to each key
• Monitor Usage: Regular monitoring of key usage and statistics

Key Lifecycle

1. Creation: Generate keys with appropriate permissions and expiry
2. Distribution: Securely share keys with authorized personnel only
3. Monitoring: Track usage patterns and identify anomalies
4. Rotation: Regular key rotation following security policies
5. Deactivation: Immediate deactivation of compromised keys

Error Handling

Common Authentication Errors

• 401 Unauthorized: Missing or invalid API key
• 403 Forbidden: Valid key but insufficient permissions
• 429 Too Many Requests: Rate limit exceeded
• 410 Gone: API key has been deactivated

Example Error Response

JSON

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has expired",
    "details": {
      "key_id": "key_12345",
      "expires_at": "2025-01-15T10:30:00Z"
    }
  }
}

Rate Limits

Authentication Endpoint Limits

• List Keys: 100 requests per hour
• Create Key: 10 requests per hour
• Get Key Details: 1000 requests per hour
• Update Key: 50 requests per hour
• Delete Key: 10 requests per hour
• Key Statistics: 100 requests per hour

Rate Limit Headers

All responses include rate limit information:

JSON

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

Proper API key management is essential for secure and reliable access
to Spartera's analytics platform. Follow these guidelines to ensure
optimal security and performance.