API Authentication and API Keys

Server Scout uses two distinct authentication methods to secure access to its API endpoints: session-based authentication for interactive use and API key authentication for programmatic access and agent communication.

Authentication Methods

Session-Based Authentication

The dashboard web interface uses session-based authentication with secure cookies. When you log in through your browser at app.serverscout.ie, the system creates an encrypted session and returns an HttpOnly cookie that your browser automatically includes in subsequent requests.

This method is ideal for building custom tools that interact with the same endpoints as the dashboard. To authenticate programmatically:

1. Send your login credentials to the authentication endpoint
2. Capture the returned session cookie
3. Include this cookie in subsequent API requests

Session cookies expire automatically and cannot be used outside of HTTPS connections.

API Key Authentication

API keys provide a secure method for agents and automated systems to authenticate with Server Scout's API. Each server receives a unique 64-character hexadecimal key during the setup process.

API keys are sent via the X-API-Key HTTP header with every request:

X-API-Key: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

This authentication method is stateless and doesn't require managing sessions or cookies, making it perfect for the lightweight Scout agent and other automated tools.

How API Keys Work

When you add a new server to Server Scout, the system automatically generates a unique API key for that server. This key serves as both identification and authentication—it tells the API which server is sending data and proves that the request is authorised.

The Scout agent stores this key locally and includes it in every data transmission. The 64-character hexadecimal format provides excellent entropy whilst remaining easily manageable by scripts and configuration files.

All API communication, regardless of authentication method, must use HTTPS to ensure keys and session data remain encrypted in transit.

API Key Security Best Practices

Treat API keys with the same security considerations as passwords:

• Never commit keys to version control systems like Git repositories
• Avoid sharing keys in plain text via email, chat, or documentation
• Use environment variables or secure configuration files when building custom integrations
• Implement proper access controls on systems that store API keys
• Monitor key usage through Server Scout's activity logs

If you suspect a key has been compromised, rotate it immediately through the dashboard.

Key Rotation

Server Scout allows you to regenerate API keys when needed. This process immediately invalidates the old key and creates a new one:

1. Navigate to your server's settings in the dashboard
2. Click "Regenerate API Key"
3. Copy the new key
4. Update your agent configuration
5. Restart the Scout agent

Important: The old key becomes invalid immediately upon regeneration. Ensure you update the agent configuration promptly to avoid monitoring interruptions.

Key Storage Location

The Scout agent stores its API key in the configuration file located at:

/opt/scout-agent/agent.env

This file contains environment variables used by the agent, including the SCOUTAPIKEY variable. The file permissions are set to restrict access to the root user only, providing an additional security layer.

When rotating keys, you'll need to update this file with the new key value and restart the agent service.

Building Custom Integrations

If you're developing custom tools that interact with Server Scout's API, choose the authentication method that best fits your use case:

• Use session authentication for interactive tools where users log in with their credentials
• Use API key authentication for automated scripts, monitoring tools, or server-to-server communication

Both methods provide secure access to the same underlying API endpoints, ensuring your custom integrations can leverage Server Scout's full monitoring capabilities whilst maintaining robust security standards.