Authentication

The LostChurn API uses API keys for authentication. Every request must include a valid API key in the Authorization header.

API Key Format

LostChurn API keys use a prefixed format that indicates the key type and environment:

Secret keys (lc_live_ and lc_test_) grant access to the full API and must be kept confidential. Never expose them in client-side code, public repositories, or logs.

Publishable keys (lc_pub_) are safe to include in client-side code. They are used by widgets to check customer payment status. Publishable keys have read-only access scoped to individual customer lookups.

Using API Keys

Include your API key in the Authorization header with the Bearer scheme:

curl https://api.lostchurn.com/v1/payments \
  -H "Authorization: Bearer lc_live_your_api_key"

Do not pass API keys as query parameters. Query parameter authentication is not supported.

Generating API Keys

1. In the LostChurn dashboard, go to Settings > API Keys.
2. Click Create API Key.
3. Enter a name for the key (e.g., "Backend Server", "CI Pipeline").
4. Select the environment: Live or Test.
5. Select the scopes you want to grant (see below).
6. Click Create.
7. Copy the key immediately -- it is only shown once.

Scopes

API keys can be scoped to limit what operations they can perform. This follows the principle of least privilege -- grant only the permissions your integration needs.

Scope Combinations

You can assign multiple scopes to a single key:

Checking Key Scopes

You can verify an API key's scopes by calling the identity endpoint:

curl https://api.lostchurn.com/v1/auth/me \
  -H "Authorization: Bearer lc_live_your_api_key"

Response:

{
  "data": {
    "key_id": "key_abc123",
    "name": "Backend Server",
    "environment": "live",
    "scopes": ["read", "write"],
    "created_at": "2025-01-15T10:30:00Z",
    "last_used_at": "2025-03-08T14:22:00Z"
  }
}

Key Rotation

Rotate API keys regularly to limit exposure from potential leaks. LostChurn supports zero-downtime rotation:

1. Go to Settings > API Keys.
2. Click Rotate next to the key you want to replace.
3. LostChurn generates a new key with the same name and scopes.
4. Both the old and new key are valid for a grace period of 24 hours.
5. Update your application to use the new key.
6. After the grace period, the old key is automatically revoked.

You can also revoke the old key immediately by clicking Revoke Old Key if you have already updated all consumers.

Rotation Best Practices

Revoking API Keys

To immediately invalidate an API key:

1. Go to Settings > API Keys.
2. Click Revoke next to the key.
3. Confirm the revocation.

Revoked keys return 401 Unauthorized on all requests. Revocation is immediate and cannot be undone. If you revoke a key by mistake, create a new one with the same scopes.

Webhook Signing Secrets

Webhook signing secrets are separate from API keys. They are used to verify the authenticity of outbound webhook payloads that LostChurn sends to your application.

Generating a Webhook Signing Secret

1. Go to Settings > Webhooks.
2. Click Create Endpoint or edit an existing endpoint.
3. The signing secret is generated automatically and displayed once.
4. Copy the secret and store it in your application's configuration.

The signing secret starts with whsec_lc_ and is used to compute HMAC-SHA256 signatures on outbound webhook payloads. See Webhooks for verification details.

Rotating Webhook Signing Secrets

1. Go to Settings > Webhooks and select the endpoint.
2. Click Rotate Secret.
3. Both secrets are valid for 24 hours.
4. Update your application to verify against the new secret.
5. The old secret is revoked after the grace period.

Test vs. Live Keys

Test keys (lc_test_) operate in a sandbox environment:

Use test keys for development, staging environments, and CI pipelines. Switch to live keys when deploying to production.

Next Steps

• API Overview -- base URL, request format, and error handling
• Webhooks -- outbound webhook events and signature verification
• Payments -- query and retry failed payments