API Keys

API keys provide programmatic access to the TridentStack Control API. Use API keys to integrate TridentStack Control with external tools, scripts, and automation workflows.

Generating a Key

1. Navigate to Settings > API Keys.
2. Click Generate Key.
3. Enter a descriptive name for the key (e.g., "CI/CD Pipeline", "Monitoring Integration", "SIEM Export").
4. Click Create.

The full API key is displayed once at creation. Copy it immediately and store it in a secure location.

warning

Treat API keys like passwords. Do not commit them to version control or share them in plaintext. Use environment variables or a secrets manager.

Key Format

API keys use the format keyId.secretKey:

abc123def456.dc16834b217de9a4f3b2c1e8...

The keyId portion identifies the key in audit logs and the API Keys settings page. The secretKey portion is the secret used for authentication.

Using the Key

Include the API key in the X-API-Key header of your HTTP requests:

curl -H "X-API-Key: your-api-key-here" \
  https://control.tridentstack.com/api/agents

All API responses are JSON. Successful requests return a 2xx status code. Error responses include a message describing the issue.

Available Endpoints

For the complete API reference with all endpoints, request/response schemas, and interactive examples, see the API Reference.

Here are a few commonly used endpoints to get started:

Method	Endpoint	Description
GET	/api/agents	List all agents with pagination
GET	/api/agents/:id	Get detailed information for a specific agent
POST	/api/agents/:id/collect-logs	Trigger log collection from an agent

Revoking Keys

To revoke an API key:

1. Navigate to Settings > API Keys.
2. Find the key by name and click Revoke.
3. Confirm the action.

Revocation is immediate. Any request using the revoked key will receive a 401 Unauthorized response. Revoked keys cannot be restored. If access is needed again, generate a new key.

tip

Create separate API keys for each integration. This makes it easy to revoke access for a single integration without affecting others.

Best Practices

• Name keys descriptively. Use names that identify the integration or automation using the key (e.g., "Splunk SIEM Export" rather than "Key 1").
• Rotate keys periodically. Generate a new key, update the integration, then revoke the old key.
• Use environment variables. Store keys in environment variables or a secrets manager rather than hardcoding them in scripts.
• Audit key usage. Review the System Audit log to monitor which keys are being used and how frequently.
• Limit key count. Only maintain active keys for integrations currently in use. Revoke keys for decommissioned integrations.