범위 제한, 예산 설정, 유효 기간이 있는 API 키를 위한 작은 오픈 소스 라이브러리

사용량 기반 데이터 기업에서 셀프 서비스(self-serve) 부문을 이끌었을 때, 가장 흔한 기능 요청 중 하나는 API 키당 크레딧 제한(credit limits)이었습니다. * 사람들은 스크립트, 팀 동료, 혹은 이제는 AI 에이전트(AI agent)에게 키를 전달하면서도, 그 키가 전체 청구 금액을 모두 써버리지 않을 것이라는 확신을 얻고 싶어 했습니다. Tanso에서도 동일한 요청을 받고 있습니다.

계정 수준(Account-level) 및 사용자 수준(user-level) 제한은 이미 존재합니다 — 그것이 엔터프라이즈 할당량 시스템(enterprise quota systems)의 역할입니다. 하지만 이들은 무겁습니다. 스타트업에게는 간단히 바로 적용할 수 있는(drop-in) 솔루션이 없었습니다. 그래서 제가 직접 하나를 작성했습니다.

agentkey는 네 가지 기능을 수행합니다:

• 키가 사용할 수 있는 금액 제한: 키당, 일별 또는 월별 예산 설정
• 키가 할 수 있는 작업 범위 제한 (Scope): 키당 최소 권한 (Least privilege)
• 만료 시점 설정: 원하는 경우 기본적으로 짧은 수명(Short-lived) 설정 가능
• 어떤 사람이 권한을 부여했는지 기록: 감사 가능한 위임 (Delegation)

격차 (The gap)

AI 에이전트(AI agents)가 이 문제를 시급하게 만들었습니다. 에이전트는 스스로 비용을 지출합니다 — 루프(loop)나 잘못된 프롬프트(prompt) 하나로 인해 누군가 대시보드를 확인하기도 전에 한 달 치 예산을 다 써버릴 수 있습니다. 그리고 대부분의 도구가 놓치고 있는 부분이 여기 있습니다: 범위 제한 키(scoped keys)는 에이전트가 '무엇을 할 수 있는지'를 알려주지만, '얼마나 쓸 수 있는지'는 알려주지 않습니다. LLM 게이트웨이(gateways)는 지출을 제한하고, ID 플랫폼(Identity platforms)은 키의 범위를 제한합니다. 둘 다 키 수준에서 수행하는 것은 없습니다. agentkey는 이 두 가지를 모두 수행합니다.

작동 방식

이것은 새로운 인증 시스템(auth system)이 아닙니다. 기존의 Postgres 키 테이블에 몇 개의 컬럼을 추가하고 작은 API를 제공할 뿐입니다.

npm install @katrinalaszlo/agentkey

범위가 제한되고, 예산이 설정되었으며, 만료 시간이 있는 키를 생성합니다:

import { AgentKey } from '@katrinalaszlo/agentkey';

const ak = new AgentKey({ pool }); // 사용자의 pg Pool
...

각 요청마다 검증하고, 호출 후 지출을 추적합니다:

const result = await ak.validate(key.key);
// { valid: true, scopes: ['proxy.chat'], budgetRemainingCents: 5000, ... }

...

예산 집행(Budget enforcement)은 원자적(atomic)으로 이루어지므로, 동시에 실행되는 에이전트 호출이 제한 범위를 초과하여 경합(race)할 수 없습니다 — 에이전트는 요청을 병렬로 실행하기 때문에 이 점이 매우 중요합니다. 또한 원한다면 Express 미들웨어(middleware)도 사용할 수 있습니다:

app.post('/api/proxy', agentKeyMiddleware(ak, { scope: 'proxy.chat' }), handler);

이것이 아닌 것 (What it's not)

이 라이브러리는 작고 집중되어 있으며, 실제 프로덕션 키 시스템에서 추출되었고, MIT 라이선스를 따릅니다. Clerk나 Auth0가 되려고 시도하지 않습니다. 만약 이미 키 테이블 (keys table)을 가지고 있고, 할당량 시스템 (quota system)을 구축하지 않고도 키별 지출 한도 (per-key spend caps)를 설정하고 싶다면, 몇 개의 컬럼과 함수 호출만으로 해결할 수 있습니다.

npm: @katrinalaszlo/agentkey · GitHub: katrinalaszlo/agentkey