Intent Declaration

An Intent is a request from your agent, pipeline, or automation to perform a sensitive operation. Declaring an intent before execution gives SilentAuth the opportunity to evaluate it against your policy, request human approval if needed, and create a cryptographic audit record.

Creating an Intent

Call createIntent() before any sensitive action. Provide the action name, parameters, and (optionally) who should approve it:

import { SilentAuth } from '@silentauth/sdk';

const sa = new SilentAuth({
  projectId: process.env.SA_PROJECT_ID,
  secretKey: process.env.SA_SECRET_KEY,
});

const intent = await sa.createIntent({
  action: 'delete_user_account',
  params: {
    userId: 'usr_abc123',
    reason: 'User requested deletion',
  },
  approvers: ['admin-team'],  // team or individual email
  expiresIn: 1800,            // seconds; default 3600
  metadata: {                 // optional context for approvers
    requestedBy: 'support-agent',
    ticket: 'TICKET-4891',
  },
});

console.log('Pending approval:', intent.approvalUrl);

Intent Response

The createIntent() call returns immediately with a pending intent object:

{
  "id": "int_xK9mNpQ2",
  "status": "pending",
  "action": "delete_user_account",
  "params": { "userId": "usr_abc123", ... },
  "approvers": ["admin-team"],
  "approval_url": "https://app.silentauth.io/approve/int_xK9mNpQ2",
  "expires_at": "2024-01-15T11:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Action Naming Convention

Use lowercase snake_case for action names. Actions are matched against your policy rules, so consistent naming matters:

Automatic Policy Evaluation

If a matching policy does not require human approval (e.g., for low-risk environments), SilentAuth will auto-approve and return a permit immediately without requiring an approver interaction:

// If auto-approved by policy:
{
  "id": "int_aBcDeFgH",
  "status": "auto_approved",
  "permit": {
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "expires_at": "2024-01-15T10:35:00Z"
  }
}