Manage workspace access control in Instantly API v2. Covers workspace member management, API key governance with scoped permissions, workspace group management (for agencies), custom tag-based resource isolation, and audit logging. Instantly uses workspace-level isolation — each workspace is a separate tenant with its own data and API keys.
Prerequisites
Instantly Hypergrowth plan or higher
Workspace admin access
API key with all:all scope (for admin operations)
Instructions
Step 1: Workspace Member Management
import { InstantlyClient } from "./src/instantly/client";
const client = new InstantlyClient();
// List workspace members
async function listMembers() {
const members = await client.request<Array<{
id: string;
email: string;
role: string;
timestamp_created: string;
}>>("/workspace-members");
console.log("Workspace Members:");
for (const m of members) {
console.log(` ${m.email} — role: ${m.role} (joined: ${m.timestamp_created})`);
}
return members;
}
// Invite new member
async function inviteMember(email: string) {
const member = await client.request<{ id: string; email: string }>("/workspace-members", {
method: "POST",
body: JSON.stringify({ email }),
});
console.log(`Invited: ${member.email} (${member.id})`);
return member;
}
// Update member role
async function updateMemberRole(memberId: string, role: string) {
await client.request(`/workspace-members/${memberId}`, {
method: "PATCH",
body: JSON.stringify({ role }),
});
}
// Remove member
async function removeMember(memberId: string) {
await client.request(`/workspace-members/${memberId}`, { method: "DELETE" });
console.log(`Removed member: ${memberId}`);
}
Step 2: API Key Governance
// Create scoped API keys for different team roles
async function createScopedKeys() {
// Analytics-only key for the marketing team
const analyticsKey = await client.request<{ id: string; key: string; name: string }>(
"/api-keys",
{
method: "POST",
body: JSON.stringify({
name: "Marketing — Analytics Read Only",
scopes: ["campaigns:read", "accounts:read"],
}),
}
);
console.log(`Analytics key: ${analyticsKey.name} (${analyticsKey.id})`);
// Campaign management key for SDR team
const sdrKey = await client.request<{ id: string; key: string; name: string }>(
"/api-keys",
{
method: "POST",
body: JSON.stringify({
name: "SDR — Campaign Management",
scopes: ["campaigns:all", "leads:all"],
}),
}
);
console.log(`SDR key: ${sdrKey.name} (${sdrKey.id})`);
// Webhook-only key for integration service
const webhookKey = await client.request<{ id: string; key: string; name: string }>(
"/api-keys",
{
method: "POST",
body: JSON.stringify({
name: "Integration Service — Webhook Handler",
scopes: ["leads:read"],
}),
}
);
console.log(`Webhook key: ${webhookKey.name} (${webhookKey.id})`);
}
// List all API keys
async function auditApiKeys() {
const keys = await client.request<Array<{
id: string; name: string; scopes: string[]; timestamp_created: string;
}>>("/api-keys");
console.log("API Keys:");
for (const key of keys) {
console.log(` ${key.name} (${key.id})`);
console.log(` Scopes: ${key.scopes.join(", ")}`);
console.log(` Created: ${key.timestamp_created}`);
}
// Flag overprivileged keys
const overprivileged = keys.filter((k) =>
k.scopes.includes("all:all") || k.scopes.includes("all:update")
);
if (overprivileged.length > 0) {
console.log(`\nWARNING: ${overprivileged.length} key(s) with all:all scope:`);
overprivileged.forEach((k) => console.log(` ${k.name} — consider reducing scope`));
}
}
// Revoke a key
async function revokeApiKey(keyId: string) {
await client.request(`/api-keys/${keyId}`, { method: "DELETE" });
console.log(`Revoked API key: ${keyId}`);
}
Step 3: Workspace Group Management (Agency Pattern)
// For agencies managing multiple client workspaces
async function manageWorkspaceGroups() {
// List workspace group members
const groupMembers = await client.request<Array<{
id: string; email: string;
}>>("/workspace-group-members");
console.log("Workspace Group Members:");
for (const m of groupMembers) {
console.log(` ${m.email} (${m.id})`);
}
// Add member to workspace group
await client.request("/workspace-group-members", {
method: "POST",
body: JSON.stringify({ email: "[email protected]" }),
});
// Get admin users
const admins = await client.request<Array<{
id: string; email: string;
}>>("/workspace-group-members/admin");
console.log("Admins:", admins.map((a) => a.email).join(", "));
}
Step 4: Custom Tags for Resource Isolation
// Use custom tags to organize campaigns and accounts by team/client
async function setupTeamTags() {
// Create tags for each team
const teams = ["SDR-West", "SDR-East", "Marketing", "Enterprise"];
for (const team of teams) {
const tag = await client.request<{ id: string; label: string }>("/custom-tags", {
method: "POST",
body: JSON.stringify({
label: team,
description: `Resources owned by ${team} team`,
}),
});
console.log(`Created tag: ${tag.label} (${tag.id})`);
}
}
// Assign tag to campaign or account
async function tagResource(tagId: string, resourceId: string) {
await client.request("/custom-tags/toggle-resource", {
method: "POST",
body: JSON.stringify({
tag_id: tagId,
resource_id: resourceId,
}),
});
}
// Filter campaigns by tag
async function getCampaignsByTeam(tagId: string) {
return client.request<Campaign[]>(`/campaigns?tag_ids=${tagId}&limit=100`);
}
// Filter accounts by tag
async function getAccountsByTeam(tagId: string) {
return client.request<Account[]>(`/accounts?tag_ids=${tagId}&limit=100`);
}
