API Keys & Authentication

Overview

API keys authenticate your webhook and API requests to DealOracle. Every external system that sends data to or reads data from DealOracle needs a valid API key.

How API Keys Work

• Each key is a unique, randomly generated token
• Keys are scoped to a specific client account — data sent with a key is automatically associated with that client
• Include the key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

• Keys have no expiration by default, but can be manually rotated or revoked at any time

Managing Keys

Generating a New Key

1. Go to Settings → API Keys
2. Click Generate New Key
3. Copy the key immediately — it is displayed only once and cannot be retrieved later
4. Give the key a descriptive name so you can identify it later

Naming Conventions

Use clear, descriptive names that identify the integration:

• Unbounce Landing Pages
• Zapier Integration
• Custom CRM Sync
• Partner Lead Feed - Acme Corp

Key Actions

Action	How	Notes
View	Settings → API Keys	See name, creation date, last used date (key value is masked)
Rename	Click the key name	Update the label without affecting the key itself
Delete	Click the trash icon	Immediately revokes the key — all requests using it will return 401
Regenerate	Delete + create new	There is no "rotate" — delete the old key and create a new one

Security Best Practices

API keys grant access to your data. Treat them like passwords.

Do

• Store keys in environment variables — Never hardcode keys in source code
• Use separate keys per integration — If one integration is compromised, you only need to revoke one key
• Rotate keys periodically — Delete old keys and generate new ones every 90 days
• Delete unused keys — If an integration is decommissioned, immediately delete its key
• Monitor usage — Check the "Last Used" column in Settings → API Keys to spot keys that haven't been used (may be stale)

Don't

• Never expose keys in client-side code — Browser JavaScript, mobile apps, or public repositories
• Never share keys via email or chat — Use a secure secrets manager or vault
• Never use one key for everything — Makes revocation difficult and increases blast radius
• Never commit keys to version control — Add .env to your .gitignore

If a Key Is Compromised

1. Immediately delete the compromised key in Settings → API Keys
2. Generate a new key
3. Update the integration with the new key
4. Review recent lead data for any unauthorized entries