Managing API Keys
Accessing API Keys
Navigate to Settings > API Keys. Requires Owner, Admin, or Editor role.
Creating an API Key
Click Create API Key and configure:
| Field | Required | Description |
|---|---|---|
| Name | Yes | Descriptive name (e.g., "Production - Marketing Events") |
| Endpoint Type | Yes | Signal Staging (behavioral signals) or Product Org Updates (workspace/account data) |
| Expiration | No | Expiration date/time. Leave empty for no expiration |
| Secret | No | When enabled, generates a shared secret. Requests must include the secret in the X-Api-Secret header |
| Payload Template | Conditional | Field mappings -- required for Product Org endpoint type only |
Click Create API Key to generate.
Copy your API key immediately. The full key (format: sk_...) is only displayed once and cannot be retrieved later.
Endpoint Types
Signal Staging (Default)
For behavioral signals: page views, form submissions, email engagement, product feature usage.
Webhook URL:
https://app.trailspark.ai/api/signal-staging/webhook/{apiKey}
Product Org Updates
For product organization/workspace data: plans, user counts, MRR, trial status, feature flags.
Webhook URL:
https://app.trailspark.ai/api/product-orgs/webhook/{apiKey}
See Product Org Updates for payload template configuration.
Using API Keys
URL Formats
# Universal webhook
POST https://app.trailspark.ai/api/signal-staging/webhook/{apiKey}
# Source-specific webhook
POST https://app.trailspark.ai/api/signal-staging/webhook/{source}/{apiKey}
# Batch webhook
POST https://app.trailspark.ai/api/signal-staging/webhook/{apiKey}/batch
# Bulk ingestion
POST https://app.trailspark.ai/api/signal-staging/bulk/{apiKey}
Example Request
1curl -X POST \
2 "https://app.trailspark.ai/api/signal-staging/webhook/YOUR_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "email": "lead@example.com",
6 "event": "form_submission",
7 "properties": {
8 "form_name": "Contact Form",
9 "page_url": "https://yoursite.com/contact"
10 }
11 }'API Key Properties
| Property | Description |
|---|---|
| Name | Descriptive label |
| Key | Partial key displayed (full key shown only at creation) |
| Created | Creation date |
| Expires | Expiration date or "Never" |
| Status | Active or Deactivated |
| Last Used | Timestamp of last webhook request |
Deactivating Keys
Click Deactivate on the key row and confirm. Deactivation immediately rejects all webhook requests using that key.
Deactivating a key affects all integrations using it. Verify no active systems depend on the key before deactivating.
Secret Verification
When a secret is configured on the API key, include it in the X-Api-Secret request header. TrailSpark hashes the provided secret with SHA256 and compares it to the stored hash.
1curl -X POST \
2 "https://app.trailspark.ai/api/signal-staging/webhook/YOUR_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "X-Api-Secret: YOUR_SECRET" \
5 -d '{"email": "lead@example.com", "event": "page_view"}'If the key has a secret configured and the header is missing or incorrect, the request is rejected with 401.
Troubleshooting
Key not working -- Verify the full key was copied, check expiration, confirm key is active, and ensure the URL format is correct.
Request rejected (401) -- The API key is invalid, expired, or deactivated. Create a new key if needed.
Request rejected (403) -- The API key's endpoint type does not match the URL. A signal_staging key cannot be used on the product-orgs endpoint and vice versa.