Generate an API key
API keys authenticate your application when it sends events to Beacon. Every SDK and direct API integration needs one.
How API keys work
API keys are scoped to your organization, not to individual products. One key can ingest events for any product your organization owns.
When the SDK sends an event, it includes the key in an Authorization: Bearer <key> header. The Beacon API uses the key to identify which organization the event belongs to.
Keys are revealed once at creation. You won’t be able to see the plaintext key again after closing the reveal dialog. Treat keys like passwords: store them in your application’s secret manager (Azure Key Vault, AWS Secrets Manager, environment variables on a deployment platform — never check them into source control).
Step 1 — Open the API Keys page
In the sidebar, expand Settings and click API Keys.
You’ll see a table of any existing keys (with their name, prefix, created date, and status). The plaintext is not shown — only the prefix (the first 8 characters of the key) for identification.
Step 2 — Create a new key
Click Create API Key in the top-right. A modal appears with one field:
| Field | Required | Notes |
|---|---|---|
| Key Name | Yes | A human-readable label. Pick a name that identifies where the key will be used — for example, “Production server” or “Inventory Manager — staging.” |
Click Create.
Step 3 — Copy the plaintext key
A second screen replaces the form. It shows:
- Your new API key — the full plaintext, displayed once.
- A Copy to clipboard button.
- A Download as .txt button that saves a text file containing the key plus a brief reminder of where it should go.
- An “I’ve saved this key securely” checkbox.
You can’t close this dialog until you’ve ticked the checkbox. There’s no Escape, no backdrop dismiss, and no X button — Beacon enforces a one-time view to make sure the key isn’t lost in a browser tab the user never reads.
Copy or download the key immediately, then tick the checkbox and click Done.
Step 4 — Store the key securely
Move the plaintext key into wherever your application reads its configuration:
- Azure-hosted apps: Azure App Configuration or Key Vault.
- AWS-hosted apps: AWS Secrets Manager or Parameter Store.
- Self-hosted servers: environment variables on the deployment platform.
- Desktop apps: an OS-level secret store (Windows Credential Manager, macOS Keychain, Linux Secret Service). Never embed the key in your installer or shipping binary.
If you accidentally close the dialog before saving the key, you’ll need to revoke the key (it’s now lost) and create a new one. There is no way to retrieve a key after the reveal dialog closes.
Rotating and revoking keys
From the API Keys table:
- Rotate generates a new plaintext for the same key name. The old plaintext stops working immediately. Use this when a key is compromised or when an employee with the key leaves.
- Revoke disables the key permanently. The plaintext stops working immediately. The row stays in the table marked “revoked” so you have an audit trail.
What’s next
You have a key. Next, install the SDK and configure it with the slug from your product and the API key you just created.
Common questions
How many keys can I create? There’s no hard limit. Most organizations use 1-3 keys total: one for production, one for staging, and one for local development. Don’t share keys across environments — rotation gets harder.
Do I need a separate key per product? No. Keys are organization-scoped. One key can send events for any product. Use one key per environment instead.
The reveal dialog closed and I lost the key — what do I do? Revoke that key from the API Keys table (its row will stay as an audit record), then create a fresh key.