@useintercept/sdk

Server-side JavaScript SDK for Intercept agent action authorization.

Status

This package is published on npm as the official server-side JavaScript SDK for Intercept. Customer backends can use it to protect risky AI-agent actions, pause for approvals, verify webhooks, and export evidence without receiving the Intercept application source code.

License

Use of this package is governed by Intercept's commercial customer terms. It is publicly installable for authorized customer integrations, but the package is not open-source software.

Install

npm install @useintercept/sdk

Use it only from trusted backend code, workers, API routes, or agent runtime services.

Quickstart

INTERCEPT_RUNTIME_KEY=ik_live_or_test_...
INTERCEPT_AGENT_ID=agent_sales_production
INTERCEPT_MODE=observe

Hosted Intercept uses https://api.interceptcontrol.com by default. Set INTERCEPT_BASE_URL only for self-hosted/private deployments. INTERCEPT_API_KEY remains supported for older integrations, but new customer backends should use INTERCEPT_RUNTIME_KEY.

Verify the handoff before sending traffic:

npx intercept doctor

import { Intercept } from '@useintercept/sdk';

const intercept = new Intercept();

const result = await intercept.protect({
  agent: process.env.INTERCEPT_AGENT_ID,
  user: user.id,
  action: 'gmail.send_email',
  idempotencyKey: `email:${message.id}`,
  resource: { recipient_type: 'external', domain: message.to.split('@')[1] },
  payloadPreview: { subject: message.subject }
}, () => sendEmail(message));

if (result.status === 'pending_approval') {
  return { status: 'waiting_for_approval', approval_id: result.approval_id };
}

return result.data;

Behavior

• Allowed actions execute the callback once.
• Denied actions throw InterceptDeniedError and do not execute the callback.
• Approval-required actions return status: 'pending_approval' and do not execute the callback.
• Enforce mode fails closed when Intercept is unavailable.
• Observe mode runs the callback and returns observe metadata.

Express Route

app.post('/api/send-email',
  intercept.express.protect({
    agent: process.env.INTERCEPT_AGENT_ID,
    user: (req) => req.user.id,
    action: 'gmail.send_email',
    idempotencyKey: (req) => `email:${req.body.message_id}`,
    resource: (req) => ({ recipient_type: 'external', domain: req.body.to.split('@')[1] })
  }),
  async (req, res) => res.json(await sendEmail(req.body))
);

Tool Wrapper

const sendEmailTool = intercept.tool({
  name: 'gmail.send_email',
  agent: 'sales-agent',
  resource: ({ to }) => ({ recipient_type: 'external', domain: to.split('@')[1] }),
  handler: ({ to, subject, body }) => sendEmail({ to, subject, body })
});

await sendEmailTool.call(message, { user: user.id, idempotencyKey: `email:${message.id}` });

Security Notes

• Use this SDK only from trusted server-side code.
• Never expose runtime keys in browsers, mobile apps, or client-side bundles.
• Store keys in a secret manager.
• Use idempotency keys for protected side effects.
• Verify webhook signatures before resuming approved work.
• Start with INTERCEPT_MODE=observe when rolling out to existing production traffic.
• Use canonical action names such as gmail.send_email, hubspot.update_deal, salesforce.update_opportunity, and slack.post_message so approval evidence is easy to review.

Examples

The repository package includes example source for local validation:

• examples/basic-authorization.js protects one action with intercept.protect.
• examples/express-protect-route.js protects an Express route.
• examples/generic-agent-tool.js wraps a custom agent tool.
• examples/approval-polling-worker.js resumes a paused action after approval.
• examples/express-webhook-receiver.js verifies signed webhook events.
• examples/customer-sdk-smoke.js checks a customer handoff configuration.

These examples use environment variables only and must never hard-code customer secrets.