인증
서버사이드 호출은 파트너 키로 인증합니다. 파트너 키는 절대 브라우저에 노출하지 마세요. 브라우저에서는 연결별 위젯 토큰만 사용합니다.
Authorization: Bearer as_partner_<prefix>_<secret>
# or
X-Partner-Key: as_partner_<prefix>_<secret>파트너 키는 /mcp 도구 호출에는 쓸 수 없습니다(관리 전용). 도구 호출은 연결마다 발급되는 MCP 키로 합니다.
핵심 개념
| 개념 | 설명 |
|---|---|
| 파트너(Partner) | 재판매 플랫폼. 파트너 키 1개로 식별됩니다. |
| 연결(Connection) | 파트너의 엔드유저 1명. external_user_id로 식별되며, 조직 + MCP 키가 자동 발급됩니다. |
| 위젯 토큰 | 연결 1개에 묶인 짧은 수명 토큰(기본 2시간). 브라우저에서 안전하게 카탈로그·토글에 사용. |
| MCP 키 | 연결 생성/회전 시 1회 반환되는 as_live_ 키. 엔드유저 AI가 /mcp에 연결할 때 사용. |
REST API (서버사이드)
모든 경로 앞에 /api/partner.
GET/api/partner/catalog
판매 가능한 서버·도구·가격을 반환합니다(중립 이름).
POST/api/partner/connections
연결을 생성하거나 기존 연결을 가져옵니다(멱등). MCP 키는 최초 1회만 반환.
{ "external_user_id": "u_8842", "display_name": "Jane" }
→ { "connection_id": "…", "mcp_url": "https://agent.store/mcp",
"api_key": "as_live_…", // first time only
"created": true }GET/api/partner/connections
연결 목록(페이지네이션: limit, offset).
GET/api/partner/connections/{id}
연결 상세 + 서버별 활성 상태.
POST/api/partner/connections/{id}/servers/{slug}
연결에 서버를 켜거나 끕니다.
{ "enabled": true }POST/api/partner/connections/{id}/token
브라우저 위젯용 연결 토큰 발급(ttl_minutes, 5~1440).
{ "ttl_minutes": 120 } → { "token": "pct_…", "expires_at": "…" }POST/api/partner/connections/{id}/rotate-key
MCP 키 회전(새 키 1회 반환).
DELETE/api/partner/connections/{id}
연결 일시중지(키 폐기, 데이터 보존).
GET/api/partner/connections/{id}/usage
연결별 사용량 롤업(days).
GET/api/partner/usage
파트너 전체 사용량 롤업(정산용).
위젯 엔드포인트 (브라우저)
연결 토큰으로 인증합니다. 키는 필요 없습니다.
GET/api/partner/widget/catalog?token=pct_…
이 연결의 활성 상태가 반영된 카탈로그.
POST/api/partner/widget/servers/{slug}?token=pct_…
이 연결의 서버를 켜고 끕니다.
{ "enabled": true }JS SDK
스크립트를 불러오면 전역 window.AgentStore가 생깁니다.
드롭인(기본 UI)
<script src="https://agent.store/sdk/agentstore.js"
data-token="pct_…" data-mount="#store"
data-lang="ko" data-theme="light" data-columns="2"></script>
<div id="store"></div>프로그램 방식
// Default UI into an element, with a change callback:
const ui = AgentStore.mount("#store", {
token: "pct_…", lang: "ko", columns: 2,
onToggle: (slug, enabled) => console.log(slug, enabled),
});
// Headless — build your own UI:
const c = AgentStore.createClient({ token: "pct_…" });
const { servers } = await c.catalog(); // [{ slug, display_name, enabled, tools_count … }]
await c.setServer("dart", true);
c.mcpUrl(); // "https://agent.store/mcp"토큰을 생략하면 미리보기(공개 카탈로그·읽기 전용) 모드로 동작합니다.
표준 규칙
어떤 플랫폼이든 이 다섯 가지를 지키면 호환됩니다.
- 1벤더 중립: 카탈로그는 중립 slug/이름으로만 노출됩니다. 업스트림 벤더명은 표준에 포함되지 않습니다.
- 2키 분리: 파트너 키(관리)·MCP 키(/mcp 호출)·위젯 토큰(브라우저)은 역할이 분리되어 서로 대체할 수 없습니다.
- 3멱등 연결: 같은 external_user_id로 다시 호출해도 새 연결을 만들지 않습니다.
- 4최소 노출: 위젯 토큰은 카탈로그·토글만 가능하며 키·사용량·결제 정보에 접근할 수 없습니다.
- 5도매 정산: 사용량은 연결·파트너 단위로 집계되어 도매 기준으로 정산됩니다.