theAuth 面向 AI 代理：身份与限定范围权限

<!-- links-top --> > theAuth is open-source auth for AI agents and humans. Star the repo on GitHub · Read the docs · Run the quickstart · theauth.dev <!-- /links-top -->

Last spring I found one API key in four places. It sat in a cron job, a Slack bot, a code-review agent, and a notebook a teammate had forgotten about. The key belonged to a human. It could read everything that human could read, and it could write most of it too.

Nothing was wrong yet. Then I asked a simple question: which of the four did that delete last Tuesday? I could not answer it. The logs said the human did it.

That is the problem this guide fixes. You will give each AI agent its own identity, its own token, and a short list of things it may do. By the end you will have a runnable script that creates agents, denies the wrong calls, logs every decision, and revokes one agent without touching the others.

I use theAuth for this, an open-source TypeScript library (@glinr/theauth). I wrote parts of it, so weigh my opinions accordingly. I will say plainly where it does not fit.

<!-- series-nav --> > This is guide 5 of 8 in the theAuth guides. It stands on its own, so you can start right here. Nothing comes before it. It is the base for guides 6 to 8.

Building for people? Start at guide 1. Building for AI agents? Start at guide 5. Every guide links to the docs page for each concept it touches. <!-- /series-nav -->

TL;DR

Prerequisites

You need Node 20 or newer, TypeScript, and a package manager. You do not need a running server or an external database. The examples use SQLite on disk so you can open the file afterward.

You also need one honest assumption: the agents in your system call tools you control. theAuth gives you the decision point. Your code must ask it before acting. If an agent can reach a database directly with its own credentials, no permission list in the world will stop it.

Why a shared key fails

A shared human key has three problems, and they stack.

First, the blast radius equals the human's permissions. A code reviewer that only needs to read pull requests inherits write access to everything.

Second, you cannot revoke one agent. Rotate the key and all four processes break at once. You wait, and the exposed key stays live.

Third, the audit trail lies. Every row names the human. Your compliance questions, and your own debugging, hit a wall.

A per-agent identity fixes all three. Each agent holds a token that maps to one row, one owner, and one permission list. The core concepts page describes the loop in one sentence: a user creates agents, agents call authorize() before acting, and every decision lands in the audit trail.

One distinction matters early. An agent is not a user. It has no email, no password, no session, and no OAuth account. It has a bearer token and a permission set. If you catch yourself wiring password reset for an agent, you want a user. The agent identity page draws that line.

Step 1: Install and create an instance

mkdir agent-identity-demo && cd agent-identity-demo
npm init -y
npm install @glinr/theauth
npm install -D tsx typescript

Now create demo.ts. I will build it up one piece at a time, and the full file is the sum of the blocks below.

import { createTheAuth } from '@glinr/theauth';

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  agents: {
    enabled: true,
    maxPerUser: 10,
    auditAll: true,
    tokenExpiry: '24h',
  },
});

Two settings deserve a note. auditAll records every authorize() call, and it defaults to on. tokenExpiry sets how long a new agent lives when you do not pass expiresAt. A 24 hour default means an agent you forget about stops working by tomorrow. I like that default. A forgotten credential should expire, not linger.

The quickstart walks through the same setup if you want the scaffolded Next.js version instead: https://docs.theauth.dev/quickstart.

Step 2: Seed an owner

Every agent has an owner, and the owner must exist as a row in theauth_users. That column is a foreign key. Skip this step and you will see FOREIGN KEY constraint failed on your first create call. Everyone hits it once.

If you already run theAuth's own auth modules, sign-up creates the row for you. In a scratch script, insert one:

import { users } from '@glinr/theauth';

theauth.db.insert(users).values({
  id: 'user-1',
  email: 'owner@example.com',
  name: 'Owner',
  createdAt: new Date(),
  updatedAt: new Date(),
}).run();

This insert pattern comes from the quickstart troubleshooting section and works for SQLite. For Postgres, the database docs list the matching call.

Step 3: Create one agent per job

Here is the rule I follow: one agent per job, not one agent per person. A nightly pull-request reviewer and a refund bot should never share an identity, even if the same human set up both.

const reviewer = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'pr-reviewer',
  type: 'autonomous',
  permissions: [
    { resource: 'mcp:github:*', actions: ['read'] },
  ],
  expiresAt: new Date(Date.now() + 7 * 24 * 3_600_000),
  metadata: { purpose: 'nightly PR review' },
});

const refunder = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'refund-bot',
  type: 'autonomous',
  permissions: [
    { resource: 'billing:refunds', actions: ['read', 'write'] },
  ],
});

console.log(reviewer.token); // kv_..., shown once

The token starts with kv_, followed by 32 random bytes in base64url, 46 characters in total. theAuth stores only the SHA-256 hash. A full database dump cannot reveal a live token.

That has a cost. You see the plaintext exactly once, at creation. Put it in your secrets manager before the process exits, or rotate to get a new one. You cannot recover it later.

Pick the right agent type

The type field takes three values.

An autonomous agent runs on its own, with no approval step unless a permission constraint demands one. Cron jobs and unattended assistants fit here. This is the default choice.

A delegated agent receives its permissions from another agent through a delegation chain. Use it for short-lived workers spun up for one task.

A service agent is a long-lived identity for infrastructure, such as an MCP server or an internal microservice. Treat it like a service account.

Mind the per-user cap

By default one user can own 10 active agents. The eleventh create call throws a plain Error with the message User <id> has reached the maximum of <n> active agents. The error has no dedicated code, and the REST endpoint reports it as a 500. Raise maxPerUser at initialization if you run a fleet, and catch the error by message, not by code.

Step 4: Check before every action

An agent identity does nothing until your code asks the question. Put one call in front of every sensitive operation.

const allowed = await theauth.authorize(reviewer.id, {
  action: 'read',
  resource: 'mcp:github:repos',
});
console.log(allowed.allowed); // true

const denied = await theauth.authorize(reviewer.id, {
  action: 'write',
  resource: 'mcp:github:repos',
});
console.log(denied.allowed, denied.reason); // false, plus a reason
console.log(denied.auditId); // links to the audit row

The result is { allowed, reason?, auditId }. The reviewer holds only read. A write on the same resource fails, and the denial lands in the audit log with its reason.

How resource patterns match

Resources are colon-separated strings. You pick the convention. mcp:github:repos, billing:refunds, and db:users:write all work. Consistency matters more than syntax.

The wildcard has one behavior that surprises people. A * segment is not a single-segment wildcard. The matcher stops at the first * and accepts everything after it, including nothing. That means mcp:github:* matches mcp:github:repos, mcp:github:repos:comments, and mcp:github itself.

Put * only in the last position. A pattern like mcp:*:repos looks like "any server, repos only," but it accepts mcp:slack:channels too. Without a wildcard, the pattern and resource must have the same number of segments. The full table lives on the permissions page.

Actions are free-form

The action list has no fixed set. read, write, execute, and delete are common, but you can define comment or refund if that reads better in your logs. theAuth checks that the requested action appears in the permission's actions array. It does not interpret the word.

Step 5: Add constraints

A permission can carry constraints, and every one must pass. This is where least privilege gets specific. "May write files" becomes "may write files under /tmp/agent/, 20 times an hour, from the office network."

const filer = await theauth.agent.create({
  ownerId: 'user-1',
  name: 'file-writer',
  type: 'autonomous',
  permissions: [
    {
      resource: 'tool:file_write',
      actions: ['execute'],
      constraints: {
        maxCallsPerHour: 20,
        allowedArgPatterns: ['^/(home/agent|tmp)/'],
        timeWindow: { start: '09:00', end: '17:00' },
        ipAllowlist: ['10.0.0.0/8'],
      },
    },
  ],
});

const outside = await theauth.authorize(filer.id, {
  action: 'execute',
  resource: 'tool:file_write',
  arguments: { path: '/etc/passwd' },
  ip: '10.1.2.3',
});
console.log(outside.all

... (truncated at the site's per-page length limit; see the source link below for the full text.)