Apply Instantly security best practices for secrets and access control.
Use when securing API keys, implementing least privilege access,
or auditing Instantly security configuration.
Trigger with phrases like "instantly security", "instantly secrets",
"secure instantly", "instantly API key security".
Secure your Instantly.ai integration with scoped API keys, least-privilege access, secret management, webhook validation, and audit logging. Instantly API v2 uses Bearer token auth with granular scope-based permissions.
Prerequisites
Instantly account with API access
Understanding of environment variable management
Access to Instantly dashboard Settings > Integrations
Instructions
Step 1: Least-Privilege API Key Scopes
Create separate API keys for different use cases with minimal required scopes.
// Key scopes follow the pattern: resource:action
// resource = campaigns, accounts, leads, etc.
// action = read, update, all
// Read-only analytics dashboard
// Scopes needed: campaigns:read, accounts:read
const ANALYTICS_KEY_SCOPES = ["campaigns:read", "accounts:read"];
// Campaign automation bot
// Scopes needed: campaigns:all, leads:all
const AUTOMATION_KEY_SCOPES = ["campaigns:all", "leads:all"];
// Webhook-only integration
// Scopes needed: leads:read (to look up lead data on events)
const WEBHOOK_KEY_SCOPES = ["leads:read"];
// AVOID: all:all gives unrestricted access — dev/test only
Use Case
Recommended Scopes
Risk Level
Analytics dashboard
campaigns:read, accounts:read
Low
Lead import tool
leads:update
Medium
Campaign launcher
campaigns:all, leads:all, accounts:read
High
Full automation
all:all
Critical — dev only
Webhook handler
leads:read
Low
Step 2: Secret Management
// NEVER hardcode API keys
// BAD:
const client = new InstantlyClient({ apiKey: "sk_live_abc123" });
// GOOD: environment variables
const client = new InstantlyClient({
apiKey: process.env.INSTANTLY_API_KEY!,
});
// BETTER: secret manager integration
import { SecretManagerServiceClient } from "@google-cloud/secret-manager";
async function getApiKey(): Promise<string> {
const client = new SecretManagerServiceClient();
const [version] = await client.accessSecretVersion({
name: "projects/my-project/secrets/instantly-api-key/versions/latest",
});
return version.payload?.data?.toString() || "";
}
// Instantly supports multiple API keys — rotate without downtime
async function rotateApiKey() {
const oldKey = process.env.INSTANTLY_API_KEY;
// 1. Create new API key via dashboard (Settings > Integrations > API)
// 2. Update secret manager / env vars with new key
// 3. Deploy with new key
// 4. Verify new key works
const client = new InstantlyClient({ apiKey: process.env.INSTANTLY_API_KEY_NEW! });
await client.getCampaigns({ limit: 1 }); // test call
// 5. Delete old key via API
// GET /api/v2/api-keys to find the old key ID
const keys = await client.request<Array<{ id: string; name: string }>>(
"/api-keys"
);
const oldKeyEntry = keys.find((k) => k.name === "old-key-name");
if (oldKeyEntry) {
await client.request(`/api-keys/${oldKeyEntry.id}`, { method: "DELETE" });
console.log("Old API key deleted");
}
}
// API Key management endpoints:
// POST /api/v2/api-keys — Create new key (name, scopes)
// GET /api/v2/api-keys — List all keys
// DELETE /api/v2/api-keys/{id} — Revoke a key
// Manage workspace members with role-based access
async function listWorkspaceMembers() {
const members = await instantly<Array<{
id: string;
email: string;
role: string;
}>>("/workspace-members");
for (const m of members) {
console.log(`${m.email}: ${m.role}`);
}
}
// Remove a member
async function removeMember(memberId: string) {
await instantly(`/workspace-members/${memberId}`, { method: "DELETE" });
}
Security Checklist
API keys stored in environment variables or secret manager
.env files listed in .gitignore
Each integration has its own scoped API key
No all:all keys in production
Webhook endpoints validate authentication
API key rotation schedule (quarterly recommended)
Audit logs reviewed periodically
Workspace members have minimum necessary roles
Block list entries for competitor/internal domains
