Managing API Keys

Accessing API Keys

Navigate to Settings > API Keys. Requires Owner or Admin role.

Info

API Keys only appears in the sidebar for Owners and Admins. Other members who navigate to the URL directly see an explanation that only workspace owners and admins can view or manage API keys, instead of the keys list.

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.

Warning

Copy your API key immediately. The full key (format: sk_...) is only displayed once and cannot be retrieved later — not even from the keys list afterward. If you lose a key, create a new one and deactivate the old one.

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

bash

curl -X POST \
  "https://app.trailspark.ai/api/signal-staging/webhook/YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "lead@example.com",
    "event": "form_submission",
    "properties": {
      "form_name": "Contact Form",
      "page_url": "https://yoursite.com/contact"
    }
  }'

API Key Properties

The Your API Keys list shows:

Keys are shown in full only when they're created. If you've lost a key, create a new one and deactivate the old one.

Property	Description
Name	Descriptive label
Key	Shortened to the first 8 and last 4 characters (e.g., `sk_abcd1234...wxyz`) — the full key is never shown again after creation, and there's no copy button on this list
Created	Creation date
Expires	Expiration date or "Never"
Status	Active or Inactive
Last Used	Timestamp of last webhook request

The list includes both active and deactivated keys, so you can confirm a key's real status at a glance.

Deactivating Keys

Click Deactivate on the key row and confirm. Deactivation immediately rejects all webhook requests using that key. The key remains visible in the list afterward, marked Inactive.

Warning

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.

bash

curl -X POST \
  "https://app.trailspark.ai/api/signal-staging/webhook/YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Api-Secret: YOUR_SECRET" \
  -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.