Authentication
Create and manage API keys for programmatic access
API Keys
Retrace uses API keys for programmatic access. Keys are scoped to an organization and inherit the creating user's role permissions.
Creating a Key
- Navigate to Manage → API Keys in the dashboard
- Click Create API Key
- Provide a descriptive name (e.g., "CI Pipeline", "SOAR Integration")
- Copy the key immediately — it's only shown once
API keys follow the format: rtrc_live_ followed by a random string.
Using a Key
Include the key in the X-API-Key header with every request:
curl https://retrace.cloud/api/v1/analyze \
-H "X-API-Key: rtrc_live_abc123..."Permissions
API keys inherit role-based permissions:
| Role | Submit Samples | View Results | Manage Keys |
|---|---|---|---|
| Admin | Yes | Yes | Yes |
| Analyst | Yes | Yes | No |
| Viewer | No | Yes | No |
Viewer-scoped keys receive 403 Forbidden when attempting to submit samples.
Revoking a Key
- Navigate to Manage → API Keys
- Find the key and click the delete icon
- Confirm revocation
Revoked keys are immediately invalidated — any in-flight requests using the key will fail.
Security Best Practices
- Rotate keys regularly — especially after team member departures
- Use descriptive names — so you know which integration each key belongs to
- Prefer analyst-scoped keys — avoid admin keys unless the integration needs to manage the organization
- Store keys in secret managers — never commit keys to source control