APIKey

API Key

Copy page

Overview

Stayforge API Keys are credentials used for authentication and authorization. All API requests must include a valid API Key in order to access resources.

---

Quick Start

Obtain an API Key

1. Sign in to the Stayforge Dashboard
2. Navigate to Settings → API Keys
3. Create a new API Key

Usage

Include the API Key in the HTTP request header:

Code
 
X-API-Key: <your_api_key>

Example request:

Code
 
curl -X GET "https://api.stayforge.net/v1/cards/org_1234567890" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx"

API Key Format

API Keys must follow this format: {prefix}{payload}.{signature}

Security Features

IP Restrictions

API Keys can be configured with IP whitelists to restrict requests to specific IP addresses or CIDR ranges:

• Empty list means no restrictions (all IPs allowed)
• Once IP ranges are configured, only requests from allowed IPs will be accepted
• IP range settings can be managed in the Dashboard

Permission Control

Each API Key has specific permission scopes (scopes) to ensure it can only access authorized resources.

Error Handling

Common Error Codes

All Error codes are present API Key Error Codes

Error Response Format

All error responses follow this structure:

Code
 
{
  "message": "Human-readable error message",
  "code": "error_code_string"
}

Error Handling Example

Code
 
// JavaScript/TypeScript
try {
  const response = await fetch('/api/endpoint', {
    headers: {
      'X-API-Key': apiKey
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.code) {
      case 'missing_api_key':
      case 'invalid_api_key':
        console.error('Authentication failed:', error.message);
        break;
        
      case 'apikey_verify_error':
      case 'ip_range_fetch_error':
        // Retryable errors - retry with exponential backoff
        await retryWithBackoff(() => fetch('/api/endpoint', options));
        break;
        
      case 'apikey_insufficient_permissions':
        console.error('Permission denied:', error.message);
        break;
        
      case 'ip_not_allowed':
        console.error('IP not allowed:', error.message);
        break;
    }
  }
} catch (error) {
  console.error('Request failed:', error);
}

Best Practices

1. Secure Storage: Store API Keys in environment variables or secure key management services, never commit them to version control
2. Regular Rotation: Regularly update API Keys to enhance security
3. Principle of Least Privilege: Only grant necessary permissions to API Keys
4. IP Restrictions: Configure IP whitelists in production environments
5. Error Handling: Implement appropriate error handling and retry logic
6. Monitoring: Monitor API Key usage and error rates

Related Resources

• Dashboard: https://dash.stayforge.io/settings/apikeys
• API Documentation: See the complete API reference documentation
• Error Code Details: Refer to API Key Error Codes Documentation
• Support Email: [email protected]

Important Notes

• Once an API Key is created, store it securely as the system will not display the complete key again
• If an API Key is compromised, immediately revoke it in the Dashboard and create a new one
• Ensure API Keys are not expired, expired keys will not work
• All API requests must use HTTPS (production environment)