API Keys

Hapnd uses API keys to authenticate requests from SDKs, the CLI, and direct API calls. Each key is scoped to a single tenant.

Creating an API Key

1. Sign in to the Hapnd Dashboard.
2. Go to Settings → API Keys.
3. Click New API Key, give it a name (e.g. local-dev or ci-pipeline), and confirm.
4. Copy the key immediately; it is shown only once.

Key Format

sk_live_abc123def456...   # Production key
sk_test_abc123def456...   # Test / sandbox key

• sk_live_ keys hit the live environment. Events appended with these keys are durable and billable.
• sk_test_ keys hit the sandbox environment. Use these in development and CI so test data never reaches production.

The CLI validates the prefix on login and rejects keys that don’t match either format.

Using Your API Key

SDK (TypeScript)

import { createHapndClient } from "@hapnd/client";

const hapnd = createHapndClient("sk_live_your_api_key");

SDK (.NET)

using Hapnd.Client;

var hapnd = new HapndClient("sk_live_your_api_key");

CLI

npx @hapnd/cli login sk_live_your_api_key

The key is stored in ~/.hapnd/config.json with 0600 permissions (owner-only read/write).

Environment Variable

Set HAPND_API_KEY to override the stored key. This takes precedence over ~/.hapnd/config.json and is the recommended approach for production deployments and CI pipelines:

HAPND_API_KEY=sk_live_your_api_key npx @hapnd/cli deploy

const hapnd = createHapndClient(process.env.HAPND_API_KEY!);

Rotating Keys

1. Create a new key in the Dashboard.
2. Update your services to use the new key.
3. Revoke the old key once all services have been updated.

There is no grace period; revoking a key immediately rejects all requests that use it.

Key Management Best Practices

• Never commit keys to source control. Use environment variables or a secrets manager.
• Use sk_test_ keys in CI. Keeps test data out of the live environment and avoids unexpected billing.
• One key per service. Makes revocation clean; you can revoke a single compromised key without rotating credentials everywhere.
• Name keys descriptively. github-actions-prod is easier to audit than key-3.