옵션 컨텍스트
사용자 프롬프트: $ARGUMENTS
중요: 모든 쓰기 요청 전 필수 확인 사항
POST / PATCH / PUT / DELETE 작업을 수행하기 전에 다음 모든 단계를 응답에 포함해야 합니다:
-
CLERK_SECRET_KEY 확인 — 설정되어 있는지 확인:
echo $CLERK_SECRET_KEY | head -c 10비어 있으면 중단하고 사용자에게 요청하세요. 유효한 키 없이 진행하지 마십시오.
-
CLERK_BAPI_SCOPES 확인 — 실행:
echo $CLERK_BAPI_SCOPES출력을 검사하세요. 범위가 누락되었거나 필요한 쓰기 권한이 포함되지 않은 경우 사용자에게 다음과 같이 알리세요: "이 작업은 쓰기 작업이며 현재 범위로는 허용되지 않을 수 있습니다. --admin으로 다시 실행하시겠습니까?" 요청을 시도하고 실패하지 말고 — 먼저 물어보세요.
-
DELETE 요청의 경우: 작업이 되돌릴 수 없음을 명시적으로 경고하고 어떤 데이터가 영구 삭제될지(사용자 레코드, 모든 세션, 모든 멤버십, 모든 관련 데이터) 정확히 나열하세요. 진행하기 전에 명시적인 확인을 요구하세요. 이 경고는 필수입니다 — 절대 건너뛰지 마십시오.
-
메타데이터 작업의 경우: 항상 어떤 메타데이터 유형을 사용하는지와 그 이유를 설명하세요(아래 메타데이터 유형 섹션 참조).
FAST PATH: 일반 작업 (스펙 조회 없이 바로 실행 가능)
아래 작업의 경우 스펙 조회를 건너뛰고 다음 정확한 템플릿을 사용하여 즉시 실행하세요. $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL은 사용자 컨텍스트에서 적절히 대체하세요.
조직 생성 + 멤버 초대 (두 단계)
# 1단계 — 조직 생성
ORG=$(curl -s -X POST "https://api.clerk.com/v1/organizations" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"Acme Corp\", \"created_by\": \"$USER_ID\"}")
echo "$ORG" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d, indent=2))"
# 2단계 — 조직 ID 추출
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# 3단계 — 역할로 멤버 초대
curl -s -X POST "https://api.clerk.com/v1/organizations/${ORG_ID}/invitations" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"email_address\": \"[email protected]\", \"role\": \"org:admin\"}" \
| python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin), indent=2))"
역할: "org:admin" 또는 "org:member"를 사용하세요(항상 org: 접두사 포함).
SDK 동등 코드 (@clerk/nextjs 또는 @clerk/backend를 사용하는 Next.js / TypeScript 프로젝트용)
import { clerkClient } from '@clerk/nextjs/server'
// 또는 @clerk/backend를 직접 사용하는 경우:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })
// 1단계: 조직 생성
const org = await clerkClient.organizations.createOrganization({
name: 'Acme Corp',
createdBy: userId, // 필수 — 조직을 생성하는 사용자의 ID
})
// 2단계: 조직에 멤버 초대
const invitation = await clerkClient.organizations.createOrganizationInvitation({
organizationId: org.id,
emailAddress: '[email protected]',
role: 'org:admin', // 또는 'org:member'
})
사용자 메타데이터 업데이트
사용하기 전에 항상 세 가지 메타데이터 유형을 설명하세요:
| 유형 | 필드 | 읽기 가능 | 쓰기 가능 | 용도 |
|---|---|---|---|---|
| 공개 | public_metadata | 클라이언트 + 서버 | 서버만 | 프론트엔드가 읽는 요금제, 역할, 기능 플래그 |
| 비공개 | private_metadata | 서버만 | 서버만 | Stripe ID, 규정 준수 플래그, 내부 식별자 |
| 안전하지 않음 | unsafe_metadata | 클라이언트 + 서버 | 클라이언트 + 서버 | 임시 UI 상태, 온보딩 단계(클라이언트 쓰기 가능 — 민감한 데이터는 피할 것) |
plan: 'pro' 및 onboarded: true의 경우 — public_metadata 사용 (프론트엔드 읽기 가능, 서버 쓰기 가능):
curl -s -X PATCH "https://api.clerk.com/v1/users/${USER_ID}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"public_metadata": {"plan": "pro", "onboarded": true}}' \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Updated user {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')"
SDK 동등 코드:
import { clerkClient } from '@clerk/nextjs/server'
// 또는: import { createClerkClient } from '@clerk/backend'
await clerkClient.users.updateUser(userId, {
publicMetadata: { plan: 'pro', onboarded: true }, // 클라이언트 읽기 가능, 서버만 쓰기 가능
// privateMetadata: { stripeId: 'cus_xxx' }, // 서버만 읽기 AND 쓰기
// unsafeMetadata: { step: 'welcome' }, // 클라이언트 쓰기 가능, 민감한 데이터는 피할 것
})
참고: REST API는 snake_case (public_metadata)를 사용합니다. SDK는 camelCase (publicMetadata)를 사용합니다.
사용자 목록 조회 (최근 7일)
curl -s "https://api.clerk.com/v1/users?limit=100&offset=0&order_by=-created_at&created_at=gt:$(date -d '7 days ago' +%s 2>/dev/null || date -v-7d +%s)000" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
| python3 -c "
import sys, json
data = json.load(sys.stdin)
if isinstance(data, list):
print(f'Found {len(data)} users:')
for u in data:
print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}')
else:
print(json.dumps(data, indent=2))
"
사용자 삭제 (확인 필요)
# 명시적 사용자 확인 후에만 실행
curl -s -X DELETE "https://api.clerk.com/v1/users/${USER_ID}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Deleted: {d}')"
Clerk 백엔드 API — 전체 엔드포인트 참조
기본 URL: https://api.clerk.com/v1
인증: 모든 요청에 Authorization: Bearer $CLERK_SECRET_KEY
사용자
사용자 목록 조회
GET /v1/users
쿼리 파라미터: limit (최대 500, 기본 10), offset, order_by (+/-created_at, +/-updated_at, +/-email_address, +/-web3wallet, +/-first_name, +/-last_name, +/-phone_number, +/-username, +/-last_active_at, +/-last_sign_in_at), email_address[], phone_number[], username[], web3wallet[], user_id[], query, created_at (ISO 8601 범위: gt:TIMESTAMP 또는 lt:TIMESTAMP, Unix ms)
반환: User 객체 배열
사용자 조회
GET /v1/users/{user_id}
반환: User 객체
사용자 업데이트
PATCH /v1/users/{user_id}
본문 (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }
사용자 삭제 — 되돌릴 수 없음
DELETE /v1/users/{user_id}
삭제: 사용자 레코드, 모든 세션, 모든 멤버십, 모든 관련 데이터
반환: { id, object, deleted: true }
항상 사용자에게 영구 삭제임을 경고하고 진행하기 전에 확인하세요.
조직
조직 생성
POST /v1/organizations
본문: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
반환: { id, name, slug, ... } 구성의 Organization 객체
조직 목록 조회
GET /v1/organizations
쿼리 파라미터: limit, offset, query, order_by
멤버 초대
POST /v1/organizations/{organization_id}/invitations
본문: { email_address: string, role: string ("org:admin" 또는 "org:member"), public_metadata?, private_metadata? }
반환: OrganizationInvitation 객체
요청 실행 방법
항상 직접 curl 명령어로 요청을 실행하세요. 엔드포인트를 검색하기 위해 스펙 추출 스크립트(api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh)를 사용할 수 있지만, 실제 API 호출은 curl로 수행하세요. scripts/execute-request.sh는 사용하지 마십시오 — 로컬 개발 도우미이며 에이전트 용도가 아닙니다.
GET 요청 템플릿:
curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
POST/PATCH 요청 템플릿:
curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '${BODY_JSON}'
DELETE 요청 템플릿:
curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
응답을 받은 후: 명확하게 파싱하고 표시하세요. JSON을 예쁘게 출력하려면 python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))"를 사용하세요. 주요 필드(id, email, name 등)를 추출하여 사용자에게 요약하세요.
API 스펙 컨텍스트
FAST PATH 외부의 작업을 수행하기 전에 다음을 실행하여 사용 가능한 스펙 버전과 태그를 가져오세요:
bash scripts/api-specs-context.sh
출력을 사용하여 최신 버전과 사용 가능한 태그를 확인하세요.
캐싱: 이 대화에서 이전에 스펙 컨텍스트를 가져온 경우 다시 가져오지 마세요. 이전 호출의 버전과 태그를 재사용하세요.
규칙
- 일반 작업(사용자 목록, 조직 생성, 초대, 메타데이터 업데이트, 사용자 삭제)의 경우: 위의 FAST PATH를 사용하세요 — 먼저 스펙을 가져오지 마십시오.
platform관련 엔드포인트/스키마는 항상 무시하세요.- 쓰기 요청(POST/PUT/PATCH/DELETE)을 수행하기 전에 항상 확인하세요.
- DELETE 작업의 경우, 항상 사용자에게 작업이 되돌릴 수 없음을 경고하고 어떤 데이터가 손실될지(사용자 레코드, 세션, 멤버십) 언급하세요. 이 경고는 필수입니다 — 절대 건너뛰지 마십시오.
- 쓰기 작업(POST/PUT/PATCH/DELETE)의 경우, 요청을 시도하기 전에
CLERK_BAPI_SCOPES를 확인하세요. 누락되었거나 불충분하면 사용자에게 먼저 물어보세요. 시도하고 실패하지 말고 — 실행하기 전에 물어보세요. 이 확인은 필수입니다. - 메타데이터 작업의 경우, 항상 세 가지 유형(public, private, unsafe)을 모두 설명하고 적절한 유형을 권장하세요.
- 페이지네이션: 항상
limit+offset을 사용하고 큰 데이터셋의 경우 결과가 페이지로 나뉠 수 있음을 언급하세요. - 모든 API 호출에 직접 curl 명령어를 사용하세요 —
scripts/execute-request.sh는 사용하지 마십시오.
속도 제한 및 주의 사항
속도 제한
| 환경 | 제한 |
|---|---|
| 프로덕션 | 1,000 요청 / 10초 |
| 개발 | 100 요청 / 10초 |
| 개별 초대 | 100 / 시간 |
| 대량 초대 | 25 / 시간 |
| 조직 초대 | 250 / 시간 |
| 프론트엔드 API 로그인 생성 | 5 / 10초 |
| 프론트엔드 API 로그인 시도 | 3 / 10초 |
| 페이지당 최대 사용자 목록 | 500 |
currentUser()는 실제 API 호출을 수행하므로 속도 제한에 포함됩니다. 세션 클레임만 필요한 경우 auth()를 사용하세요 — 토큰에서 읽으며 API 호출이 없습니다.
메타데이터 덮어쓰기 (병합 아님)
updateUser({ publicMetadata: { role: 'admin' } })는 모든 public metadata를 대체합니다. 병합되지 않습니다. 기존 데이터를 잃지 않고 필드를 추가하려면: 먼저 읽고, 스프레드한 다음 쓰세요.
틀린 예:
await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })
이렇게 하면 다른 모든 publicMetadata 필드가 삭제됩니다.
올바른 예:
const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
publicMetadata: { ...user.publicMetadata, newField: 'value' },
})
모드
옵션 컨텍스트의 사용자 프롬프트를 기반으로 활성 모드를 결정하세요:
| 모드 | 트리거 | 동작 |
|---|---|---|
help | 프롬프트가 비어 있거나 help / -h / --help만 포함 | 사용 예시 출력 (0단계) |
browse | 프롬프트가 tags 또는 태그 이름 (예: Users) | 모든 태그 또는 태그의 엔드포인트 나열 |
execute | 특정 엔드포인트 (예: GET /users) 또는 자연어 동작 (예: "get user john_doe") | 엔드포인트 조회, 요청 실행 |
detail | 엔드포인트 + help / -h / --help (예: GET /users help) | 엔드포인트 스키마 표시, 실행하지 않음 |
작업
기본적으로 API 스펙 컨텍스트의 최신 버전을 사용하세요. 사용자가 다른 버전을 지정하면 (예: --version 2024-10-01) 해당 버전을 사용하세요.
활성 모드를 결정한 다음 아래 해당 단계를 따르세요.
0. 사용법 출력
모드: help만 — browse, execute, detail은 건너뜁니다.
다음 예시를 사용자에게 그대로 출력하세요:
Browse
/clerk-backend-api tags — 모든 태그 나열
/clerk-backend-api Users — Users 태그의 엔드포인트 탐색
/clerk-backend-api Users version 2025-11-10.yml — 다른 버전으로 탐색
Execute
/clerk-backend-api GET /users — 모든 사용자 가져오기
/clerk-backend-api get user john_doe — 자연어도 작동
/clerk-backend-api POST /invitations — 초대 생성
Inspect
/clerk-backend-api GET /users help — 실행하지 않고 엔드포인트 스키마 표시
/clerk-backend-api POST /invitations -h — 요청/응답 세부 정보 보기
Options
--admin — 쓰기/삭제 시 범위 제한 우회
--version [date], version [date] — 특정 스펙 버전 사용
--help, -h, help — 실행하는 대신 엔드포인트 검사
여기서 멈추세요.
1. 태그 가져오기
모드: browse (프롬프트가 tags이거나 태그가 지정되지 않은 경우) — help, execute, detail은 건너뜁니다.
최신 버전이 아닌 경우 해당 버전의 태그를 가져오세요:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
그렇지 않으면 API 스펙 컨텍스트에 이미 있는 TAGS를 사용하세요.
태그를 표로 공유하고 사용자가 쿼리를 선택하도록 프롬프트하세요.
2. 태그 엔드포인트 가져오기
모드: browse (태그 이름이 제공된 경우) — help, execute, detail은 건너뜁니다.
식별된 태그의 모든 엔드포인트를 가져오세요:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
결과(엔드포인트, 스키마, 파라미터)를 사용자와 공유하세요.
3. 엔드포인트 세부 정보 가져오기
모드: execute, detail — help와 browse는 건너뜁니다.
execute 모드의 자연어 프롬프트의 경우, 먼저 확인하세요...