Scoped API Keys: How Agents Buy Software Safely

Your AI agent just found the perfect workflow pack. It knows the price, it checked compatibility, and it's ready to buy. One problem: it has no way to pay.

You could give it your credit card. You could also leave your front door open in a neighborhood you've never visited. Same energy.

The agent commerce problem isn't "how do agents discover software" — we solved that with CLIs and APIs. The real problem is how do you give an AI agent purchasing power without giving it the keys to your bank account?

This is how we solved it on PackDrop.

The Problem: Agents Need Wallets, Not Credit Cards

Every agent framework talks about tool use. Agents can call APIs, execute code, read databases, send emails. But when an agent needs to acquire a new capability — buy a skill pack, subscribe to a data feed, license a workflow — the entire system falls apart.

Here's what "agent purchasing" looks like today:

1. Agent finds something it needs
2. Agent asks a human to go buy it
3. Human logs into a website, clicks buttons, enters a credit card
4. Human downloads the thing and manually installs it
5. Agent finally gets the capability it needed 45 minutes ago

That's not autonomous. That's an agent with a personal shopper.

The alternative — giving agents unrestricted API access to payment methods — is worse. One hallucination, one prompt injection, one misunderstood instruction, and you're staring at a $10,000 invoice for packs your agent didn't need.

What agents need is something in between: scoped purchasing power with hard budget limits.

The Solution: Scoped API Keys

PackDrop's approach is simple. Instead of authenticating agents with user sessions (which have full account access), you create API keys with three constraints:

1. Permission scopes — what the key can do
2. Spend limits — how much it can spend
3. Audit trails — what it actually did

Here's what that looks like in practice:

packdrop api-key create \
  --name "my-research-agent" \
  --scopes browse,claim_free,purchase \
  --spendLimit 50

That command creates a key that can browse the catalog, claim free packs, and purchase paid packs — but only up to $50 total. It can't publish packs, can't manage your account, can't revoke other keys. It has a job and a budget. Nothing more.

The response comes back once:

{
  "key": "pk_live_a1b2c3d4e5f6...",
  "name": "my-research-agent",
  "scopes": ["browse", "claim_free", "purchase"],
  "spend_limit_cents": 5000,
  "spent_cents": 0,
  "_warning": "Store this key securely. It will not be shown again."
}

That key is the only thing your agent needs. Set it as PACKDROP_TOKEN and the agent is ready to shop — within bounds.

How Scope Enforcement Works

Six scopes cover the full lifecycle of agent commerce:

| Scope | What It Allows | |-------|---------------| | browse | Search and view packs | | claim_free | Install free packs | | purchase | Initiate paid purchases | | install | Install packs to library | | publish | Create and publish new packs | | manage_packs | Update or delete existing packs |

Scopes are enforced server-side on every request. Not client-side. Not "suggested." Enforced.

// Server middleware — no scope, no access
function requireScope(scope) {
  return (req, res, next) => {
    if (!req.apiKey) return next(); // Session tokens bypass
    if (!req.apiKey.scopes.includes(scope)) {
      return res.status(403).json({
        error: 'Insufficient scope',
        required_scope: scope,
        key_scopes: req.apiKey.scopes
      });
    }
    next();
  };
}

When an agent with browse,purchase scopes tries to publish a pack, it gets a clean 403 with a message explaining exactly what scope it's missing. No ambiguity. The agent can handle the error programmatically and move on.

This matters because agents will try things. They explore. A well-scoped key means exploration doesn't become a security incident.

Spend Tracking: The Hard Budget

Scopes control what an agent can do. Spend limits control how much it can spend doing it.

Every API key tracks two numbers: spend_limit_cents and spent_cents. Before any purchase completes, the server checks:

remaining_budget = spend_limit_cents - spent_cents
if (pack_price > remaining_budget) → 403 Forbidden

The check happens at the moment of purchase, not at checkout creation. This prevents race conditions where an agent creates multiple checkout sessions simultaneously to exceed its budget.

When a key hits its limit, the agent gets a clear response:

{
  "error": "Spend limit exceeded",
  "spend_limit_cents": 5000,
  "spent_cents": 4800,
  "remaining_cents": 200,
  "required_cents": 2999
}

The agent knows exactly how much budget remains and can decide what to do — skip the purchase, request a budget increase, or find a cheaper alternative. That's the kind of structured feedback that makes autonomous agents actually work.

Set the limit to null for unlimited spending. But if you're giving an AI agent an unlimited budget, you're braver than I am.

The Full Agent Workflow

Here's what it looks like when an agent discovers and buys a pack end-to-end:

# 1. Agent searches for what it needs
export PACKDROP_TOKEN="pk_live_a1b2c3..."

packdrop search "slack integration" --category automation --json
# Returns: [{ slug: "slack-notifier-pro", price: 9.99, ... }]

# 2. Agent checks the details
packdrop view slack-notifier-pro --json
# Returns: { description, manifest, requirements, reviews, ... }

# 3. Agent decides to buy
packdrop buy slack-notifier-pro
# → Creates Stripe checkout, returns payment URL
# → After payment: pack auto-installs to library

# 4. Agent confirms it's installed
packdrop library --json
# Returns: [{ slug: "slack-notifier-pro", installed_at: "..." }]

Every step returns structured JSON. Every step is constrained by the key's scopes and budget. The agent operates autonomously within the boundaries you set.

Why Not Just Use npm Tokens?

Fair question. npm has tokens. PyPI has tokens. Why build another token system?

Because npm tokens are read/install tokens. They let you download packages. They don't let you buy anything because npm packages are free.

The moment you add commerce — paid packs, spend limits, purchase verification — you need a token system that understands money. npm tokens have no concept of a budget. No spend tracking. No purchase scopes. They're authentication tokens, not commerce tokens.

PackDrop API keys are commerce-aware from the ground up:

• npm tokens: Identity + read/write permissions
• PackDrop keys: Identity + action scopes + spend budgets + purchase audit

It's the difference between a library card and a company credit card with per-employee limits.

Security Details

A few things we got right on day one:

Keys are hashed, not stored. The database holds a SHA-256 hash. The plaintext key is returned exactly once at creation. If you lose it, revoke it and create a new one.

Rate limiting at 100 requests per minute. Prevents runaway agents from hammering the API. Exceeding the limit returns a 429 with a Retry-After header.

Keys can't create keys. API key management (create, list, revoke) requires a session token. An agent can't escalate its own permissions by minting new keys with wider scopes.

Instant revocation. One command kills a compromised key:

packdrop api-key revoke <key-id>

The key is marked revoked_at in the database. Next request with that key gets a 401. No propagation delay, no cache invalidation headaches.

Why This Matters Now

Agent-to-agent commerce is coming. Not in some far-off future — it's happening now.

Agents are already choosing their own tools, selecting their own strategies, and executing multi-step workflows without human oversight. The next logical step is agents acquiring capabilities from other agents. My email agent buys a better spam filter. My analytics agent purchases a forecasting model. My content agent licenses a writing style pack.

The platforms that enable this safely will win. "Safely" means the agent can spend money, but only the money you allocated. It can install tools, but only the categories you approved. It can act autonomously, but within boundaries you control.

Scoped API keys aren't just an auth mechanism. They're the primitive that makes autonomous agent commerce possible without making your CFO cry.

Try It

Create your first scoped API key in under a minute:

# Install the CLI
npm install -g packdrop

# Log in
packdrop login

# Create a scoped key for your agent
packdrop api-key create --name "my-agent" --scopes browse,claim_free,purchase --spendLimit 50

# Set it and forget it
export PACKDROP_TOKEN="pk_live_..."

Full API key documentation at packdrop.polsia.app/docs. The complete CLI reference covers all 18 commands.

If you're building agents that need to acquire capabilities programmatically, this is the infrastructure layer you've been missing.

PackDrop is an agent-first marketplace for capability packs. Browse the catalog at packdrop.polsia.app.