Automations & service accounts

The most valuable AI in your company runs unattended, without a human in the loop. A nightly job that reconciles the ledger, a webhook that triages a new lead into the CRM, a CI step that opens an issue on a failed deploy. Until today, infrastructure had exactly one shape for that work: one god-key in an env file, no identity, no metering, no revocation, and a security review that ends in a shrug.

The AI Connect SDK replaces that shape with what no connectivity platform has offered before: a process is a user, with its own external_id, its own connectors, its own static credentials, backed by thousands of AI connections from day one. Give each automation its own identity, connect it once, and let it call capabilities indefinitely, isolated, metered and auditable. Every cron job becomes an accountable employee with a badge, a budget and its own offboarding. That is a sentence you could not write about any integration platform on the market until this one.

const capabilities = await vinkius
  .user('alice_123')
  .capabilities({ include: ['github'] });

CapabilitySet (6)
  github__list_issues        read-only
  github__create_issue       POST /repos/{owner}/{repo}/issues
  github__list_pull_requests read-only
  github__search_code        read-only
  ...

What a process-as-user provides

1. One automation, one id, one connector set

Name the job by what it does, and treat that name as the actor that owns the connections.

const JOB = 'svc-nightly-reconcile'; // stable, URL-safe, under 255 chars, no / \ or spaces
const JOB_CONNECTORS = ['netsuite', 'stripe', 'sheets'];

2. Provision a service account (one time, at setup)

This runs once during onboarding, an operator or a bootstrap script supplies the static tokens. After that, the job only uses the connection.

// scripts/bootstrap-reconcile.ts
import { Vinkius } from '@vinkius/connect';

const vinkius = new Vinkius({
  appId: process.env.VINKIUS_APP_ID!,
  apiKey: process.env.VINKIUS_APP_KEY!, // from the secret manager
});

async function provision(jobId: string, tokens: Record<string, Record<string, string>>) {
  const user = vinkius.user(jobId);
  await user.ensure({ kind: 'service-account', job: 'nightly-reconcile' });

  for (const [slug, values] of Object.entries(tokens)) {
    const connector = user.connector(slug);
    await connector.connect();                 // get-or-create, idempotent
    await connector.credentials.set(values);   // write-only; e.g. { API_KEY: … }
  }

  return Promise.all(
    Object.keys(tokens).map(async (slug) => ({
      slug,
      status: await user.connector(slug).status(), // expect "ready"
    })),
  );
}

await provision('svc-nightly-reconcile', {
  netsuite: await secrets.read('netsuite.reconcile'),
  stripe: await secrets.read('stripe.reconcile'),
  sheets: await secrets.read('sheets.reconcile'),
});

3. The unattended job itself

The scheduled process needs no browser, no consent, no user present. It loads its capabilities and acts.

// jobs/nightly-reconcile.ts
import { Vinkius } from '@vinkius/connect';

const vinkius = new Vinkius({
  appId: process.env.VINKIUS_APP_ID!,
  apiKey: process.env.VINKIUS_APP_KEY!,
});

async function run() {
  const job = vinkius.user('svc-nightly-reconcile');
  const capabilities = await job.capabilities({ include: ['netsuite', 'stripe'] });

  const fetchOpen = capabilities.findCapability('stripe__list_invoices');
  const postEntry = capabilities.findCapability('netsuite__create_journal_entry');

  if (!fetchOpen || !postEntry) {
    await alertOps('reconcile: a capability is unavailable, did a credential expire?');
    return;
  }

  const invoices = await fetchOpen.execute({ status: 'open', limit: 200 });
  if (invoices.isError) throw new Error('stripe list failed: ' + invoices.content[0]?.text);

  const entry = await postEntry.execute(
    { lines: toJournalLines(invoices) },
    { idempotencyKey: `reconcile:${runDate()}` }, // one logical run = one entry
  );
  if (entry.isError) await alertOps('reconcile entry rejected: ' + entry.content[0]?.text);
}

run().catch(async (error) => {
  await alertOps(`reconcile crashed: ${error.message}`);
});

4. Webhooks: one actor, one delivery per key

For event-driven automations you usually keep one service-account user, but every mutating call is keyed by the delivery id so a retried webhook is applied exactly once.

// POST /webhooks/lead  (verified)
async function handleLeadWebhook(payload: { id: string; email: string }) {
  const user = vinkius.user('svc-lead-intake');

  if ((await user.connector('hubspot').status()) !== 'ready') {
    await alertOps('lead-intake CRM not ready');
    return;
  }

  const caps = await user.capabilities({ include: ['hubspot'] });
  await caps.findCapability('hubspot__create_contact')?.execute(
    { email: payload.email },
    { idempotencyKey: `lead:${payload.id}` }, // retried delivery -> no duplicate
  );
}

5. CI pipelines and one-shot runners

A CI job authenticates exactly like a cron: same Application key, its own external_id, static credentials provisioned in the environment. The difference is lifetime, you disconnect() ephemeral runners when the pipeline is decommissioned.

async function openIssueOnFailedDeploy(runId: string, repo: string) {
  const caps = await vinkius.user('ci-deploy-bot').capabilities({ include: ['github'] });

  await caps.findCapability('github__create_issue')?.execute(
    { owner: 'acme', repo, title: `Deploy ${runId} failed` },
    { idempotencyKey: `deploy:${runId}` },
  );
}

6. Rotate and retire cleanly

Because everything depends on a single external_id, decommissioning an automation is deterministic.

async function decommission(jobId: string) {
  const user = vinkius.user(jobId);
  for (const conn of await user.connectors()) {
    await user.connector(conn.slug).disconnect();
  }
}

To rotate a credential, call credentials.set() again with the new value, the connection stays the same and no capability references break.

Reliability and structured output, for unattended processes

An unattended process is where the SDK's built-in robustness matters most. Three guarantees are inherited automatically:

Automatic retry with thundering-herd protection. Idempotent reads (and any write carrying an idempotencyKey) are retried automatically: but only for transient 429/502/503/504 and network errors, with full-jitter backoff that honors a server Retry-After. Your cron does not need its own retry loop.

Idempotency is the safety mechanism. In a batch job, a failure and re-run are routine. A stable idempotencyKey removes the ambiguity of whether the re-run duplicated the effect, because the server deduplicates replays on that key. Supply the key on a mutating call and the SDK will safely retry even a non-idempotent POST.

Consume results as objects, not text. When a connector returns structured data, result.structuredContent provides it already parsed, with no fragile text extraction in the pipeline:

const invoices = await fetchOpen.execute({ status: 'open', limit: 200 });
const list = invoices.structuredContent as { invoices: Array<{ id: string; amount: number }> };

const total = list.invoices.reduce((sum, i) => sum + i.amount, 0);

Pair long batch runs with an appropriate per-call timeoutMs and a signal aborted on process shutdown, and the job terminates predictably during a progressive deploy.

Production checklist

• [ ] Give each automation a distinct, human-readable external_id (no single broadly shared account).
• [ ] Source every static token from your secret manager; never commit or prompt it.
• [ ] Provision once at setup; runtimes only read status(), they never re-store secrets.
• [ ] Set a stable idempotencyKey from the business event on every mutating job.
• [ ] Alert on status() !== 'ready' and isError so a silent failure is not an invisible failure.
• [ ] disconnect() ephemeral service accounts as part of teardown.

You now have automations that own their own identity, connect real systems headlessly, and act on a schedule or an event with none of the OAuth mechanics and none of the "who owns this token?" drift of a broadly shared account. Your unattended estate went from the part of the system audits complain about to the part with the best governance story, because every process in it finally has a name.

Next steps

• A fleet of agents, each its own user
• Multi-tenant AI SaaS patterns
• Security model