API Reference — Agent Approval Gate

Server-to-server endpoints called by AI agents (or their SDK / MCP). Mobile-facing endpoints (사용자 결정 흐름) 은 별도 — 일반 RP 가 호출할 일 없음.

Base URL: https://api.1pass.dev

Authentication

모든 요청은 다음 헤더 필수:

헤더	설명
Authorization: Bearer logi_agt_...	콘솔에서 발급한 토큰
Idempotency-Key: <unique>	재시도 안전성. 동일 키 재전송 시 같은 row 반환
Content-Type: application/json	본문은 항상 JSON

signed 모드 는 추가로:

헤더	설명
X-Agent-Timestamp	Unix epoch seconds. 서버 시각 ±5분
X-Agent-Nonce	32+ hex chars. 5분 윈도우 내 재사용 불가
X-Agent-Signature	base64(Ed25519(canonical))

Canonical 서명 문자열:

METHOD\n
PATH\n
TIMESTAMP\n
NONCE\n
SHA256(BODY)\n
AGENT_PUBLIC_ID

SDK / MCP 서버가 이 부분을 자동 처리합니다.

Endpoints

POST /api/agents/approvals

새 승인 요청 생성. CIBA auth_req_id 발급.

Request

{
  "action_type": "meta.ads.budget_change",
  "title": "Meta 광고 예산 변경",
  "body": "캠페인 Q3-launch 일 예산 500,000원 → 50,000,000원 (×100)",
  "context": {
    "campaign_id": "abc123",
    "from": 500000,
    "to": 50000000,
    "currency": "KRW"
  },
  "ttl_seconds": 300
}

Response 201 Created (또는 200 OK on idempotent replay)

{
  "auth_req_id": "aar_xxxxxxxxxxxxxxxx",
  "status": "pending",
  "action_type": "meta.ads.budget_change",
  "number_match": "428193",
  "display_payload_hash": "f5c1...64hex",
  "expires_in": 300,
  "interval": 2
}

Errors

• 401 invalid_token — 토큰 없음/만료/취소
• 401 invalid_signature — 서명 / nonce / timestamp 문제
• 401 nonce_replay — 5분 윈도우 내 nonce 재사용
• 401 missing_idempotency_key — Idempotency-Key 헤더 누락
• 403 action_not_allowed — 에이전트의 allowed_action_types 화이트리스트 위반
• 403 ip_not_allowed — 에이전트의 allowed_ips 화이트리스트 위반
• 403 bearer_only_disabled — 환경 정책상 bearer_only 비활성
• 429 cool_down_active — 같은 action_type 직전 거절 (10분 lock)
• 429 rate_limited — 분당 한도 초과

GET /api/agents/approvals/:auth_req_id

상태 폴링. CIBA interval 필드의 초 단위로 폴링하면 됨 (기본 2초).

Response 200

{
  "auth_req_id": "aar_xxxxxxxxxxxxxxxx",
  "status": "approved",
  "decided_at": "2026-05-17T08:42:31Z",
  "interval": 2,
  "expires_in": 0
}

가능한 status:

• pending — 푸시 발송 전
• delivered — 푸시 발송됨, 사용자 결정 대기
• approved — 사용자가 Face ID 후 승인
• rejected — 사용자가 명시적 거절
• expired — TTL 초과 (자동 거절)
• revoked — 에이전트가 자발적 취소 또는 자격증명 회전으로 무효화

POST /api/agents/approvals/:auth_req_id/cancel

에이전트 측에서 자발적 취소. 사용자가 무관한 알림을 받지 않도록 즉시 in-flight 종료.

Response 200 — status: "revoked" 로 전이된 row 반환.

Rate Limits

차원	기본
에이전트당 분당	60 요청 (controller rate_limit + Rack::Attack 이중)
사용자당 분당	120 요청 (모든 에이전트 합산)
IP 당 분당	120 요청
동일 action_type 거절 후	10분 cool-down

초과 시 429 + Retry-After 헤더 반환.

CIBA 매핑

OpenID Connect CIBA spec	logi 필드
auth_req_id	auth_req_id
expires_in	expires_in
interval	interval
Poll mode	GET /api/agents/approvals/:id
Ping mode	(Phase 2 — webhook 옵션)
Push mode	(Phase 2 — webhook 옵션)