Skip to content
NewSee how

How to Create & Manage Developer API Keys in FirstSales

Mint least-privilege API keys with per-resource scopes, use them with the CLI and REST API, and rotate or revoke them safely without an outage.

Tutorials
Developer & CLI
min read
7 min
steps
6 · Intermediate

  1. Open Settings → API

    API keys live under Settings → API. This is where you mint the credential that authenticates the CLI and any direct calls to https://api.app.firstsales.io. You need the right permission to see this tab.

  2. Create a key with least-privilege scopes

    Click to create a key, give it a name (something that says where it's used, e.g. "ci-contact-sync"), and check only the scopes it needs. Scopes are per-resource and split read vs write: e.g. contacts:read, contacts:write, campaigns:read, kb:read. There's a * scope that grants everything; avoid it unless you truly need full access.

    Create a key with least-privilege scopes

  3. Copy the key immediately

    The full key is shown exactly once: "Copy this key now. It will not be shown again." Copy it straight into your secret store or password manager. If you lose it, you can't recover it; you revoke and create a new one. Never paste it into code, chat, or a commit.

  4. Use it with the CLI

    Export the key as FIRSTSALES_API_KEY and the CLI picks it up automatically. Verify with whoami before doing anything else:

    export FIRSTSALES_API_KEY="fs_live_..."   # from your secret store, never hardcoded
firstsales whoami --json

  5. Use it with the API directly

    For raw HTTP, send the key as a Bearer token. Start with whoami to confirm the key resolves and to read back which org/workspace it can reach:

    curl -s https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

  6. Rotate and revoke

    Each key on the list can be revoked, and revocation is immediate with no undo: any CLI or service using it fails on the next call. To rotate: create the new key, deploy it to your secret store, confirm the new one works, then revoke the old one. Revoke instantly if a key is ever exposed.

Pro tips

  • One key per consumer

    Give CI, your laptop, and each integration its own named key. When one leaks or a service is retired, you revoke just that key instead of breaking everything.

  • Least privilege beats convenience

    A read-only sync doesn't need contacts:write, and almost nothing needs `*`. Scope tight: a leaked read-only key can't mutate your data.

  • Copy once, store in a secret manager

    The key is shown a single time. Paste it directly into your CI secret store or password manager: never into source, a .env you might commit, or a chat message.

  • Rotate by overlap, not gap

    Create-deploy-verify-then-revoke. Revoking before the replacement is live causes an outage; the overlap window keeps calls flowing during rotation.

Frequently asked questions

Where do I create an API key?

Settings → API. Give it a name, check the scopes it needs, and create. The key authenticates both the CLI and direct API calls.

What are scopes?

Per-resource permissions, split read vs write: e.g. contacts:read, campaigns:write, kb:read, plus a * that grants everything. Check only what the key's consumer needs.

I lost my key: can I see it again?

No. The full key is shown once at creation (“It will not be shown again”). If you lose it, revoke that key and create a new one.

How does the CLI use the key?

Set it as the FIRSTSALES_API_KEY environment variable; the CLI reads it automatically. Run firstsales whoami to confirm it works.

How do I revoke a key?

On the API settings list, revoke it. Revocation is immediate and permanent: anything using that key fails on its next call, so rotate a replacement in first.

How should I rotate keys safely?

Create the new key, deploy it, confirm it works, then revoke the old one. This overlap avoids an outage. Revoke immediately (no overlap) only if a key is exposed.

Developer & CLI

Outreach that keeps going after you log off.Leads, emails, follow-ups and replies, handled.

Connect unlimited mailboxes and let AI agents find leads, write each email and follow up. Or send your own templates in manual mode. From $29/mo.

Start your $1 trial See pricing

$1 for 3 days · Cancel anytime · No contract

Install with AI

Your coding agent sets up the FirstSales CLI and skills for you.

Prompt for Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗