Documentation

Build agent tools that never run on stale credentials.

nominee sits between your agent framework and your user’s third-party accounts. Ask for a token at execution time; nominee handles caching, refresh, approval, and audit events.

Install

npm i nominee

The core package has zero runtime dependencies. Start with a plain token resolver, then add adapters or managed strategies when you need them.

Quickstart

import { Nominee, tokens } from 'nominee'

const nominee = new Nominee({
  strategy: tokens(async ({ user, connection }) =>
    db.getFreshToken(user, connection)
  ),
  onAudit: (event) => auditDb.insert(event),
  agent: 'triage-bot',
})

const token = await nominee.token({
  user: 'alice',
  connection: 'github',
})

Do not store the returned access token in your own agent state. Call nominee.token() at the moment the tool runs.

Strategies

tokens(fn)

Wrap an env var, database lookup, or any function that returns a token.

OAuth2()

Use a generic refresh-token flow without adding provider dependencies.

Memory()

Seed tokens in memory for development, examples, and tests.

Auth0()

Optional managed strategy for Token Vault and CIBA approval flows.

Human approval

await nominee.approve({
  user: 'alice',
  action: 'repo.delete',
  detail: 'Delete repository: alice/old-project',
})

nominee.resolveApproval(approvalId, 'approved')

If the active strategy implements native approval, nominee delegates to it. Otherwise the built-in approval engine pauses until your webhook resolves the request.

Framework adapters

npm i nominee nominee-ai

import { nomineeTool } from 'nominee-ai'
import { z } from 'zod'

const starRepo = nomineeTool({
  nominee,
  user: 'alice',
  connection: 'github',
  description: 'Star a GitHub repository',
  inputSchema: z.object({ repo: z.string() }),
  execute: async ({ repo }, ctx) => {
    await fetch(`https://api.github.com/user/starred/${repo}`, {
      method: 'PUT',
      headers: { Authorization: `Bearer ${ctx.token}` },
    })
    return `Starred ${repo}`
  },
})

Use nominee-ai for Vercel AI SDK and Cloudflare Agents. Use nominee-eve for Vercel Eve.

Core API

await nominee.token({ user, connection }) await nominee.approve({ user, action, detail }) nominee.resolveApproval(id, 'approved' | 'denied') await nominee.can({ user, action, resource }) nominee.on((event) => auditDb.insert(event))