Communitygithub.com

Clerk 백엔드 REST API 탐색기 및 실행기

태그 탐색, 엔드포인트 스키마 검사, 인증된 요청 실행. 사용자 목록 조회, 조직 관리, 또는 Clerk API 엔드포인트 호출 시 사용합니다.

Clerk 백엔드 REST API 탐색기 및 실행기란 무엇인가요?

이 기술은 Clerk 백엔드 REST API를 탐색하고 실행하기 위한 AI 에이전트 도구입니다. 사용자, 조직, 초대, 메타데이터 등 주요 Clerk API 엔드포인트를 빠르게 찾고 호출할 수 있습니다. **주요 기능:** - **FAST PATH**: 일반적인 작업(사용자 목록, 조직 생성, 멤버 초대, 메타데이터 업데이트, 사용자 삭제)은 사전 스펙 조회 없이 바로 실행. - **안전장치**: 쓰기/삭제 작업 전 `CLERK_SECRET_KEY`와 `CLERK_BAPI_SCOPES`를 확인하고, 삭제 시에는 되돌릴 수 없음을 경고하며 명시적 확인을 요구. - **메타데이터 유형 설명**: public, private, unsafe 세 가지 메타데이터 유형을 항상 설명하고 적절한 유형을 추천. - **모드 기반 동작**: `help`, `browse`, `execute`, `detail` 모드로 구분되어 사용자 의도에 맞게 응답. **지원 플랫폼:** CLI(curl 명령어), SDK(TypeScript/Next.js)를 모두 지원합니다. 모든 API 호출은 직접 curl 명령어로 실행됩니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-backend-api

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

옵션 컨텍스트

사용자 프롬프트: $ARGUMENTS

중요: 모든 쓰기 요청 전 필수 확인 사항

POST / PATCH / PUT / DELETE 작업을 수행하기 전에 다음 모든 단계를 응답에 포함해야 합니다:

  1. CLERK_SECRET_KEY 확인 — 설정되어 있는지 확인:

    echo $CLERK_SECRET_KEY | head -c 10
    

    비어 있으면 중단하고 사용자에게 요청하세요. 유효한 키 없이 진행하지 마십시오.

  2. CLERK_BAPI_SCOPES 확인 — 실행:

    echo $CLERK_BAPI_SCOPES
    

    출력을 검사하세요. 범위가 누락되었거나 필요한 쓰기 권한이 포함되지 않은 경우 사용자에게 다음과 같이 알리세요: "이 작업은 쓰기 작업이며 현재 범위로는 허용되지 않을 수 있습니다. --admin으로 다시 실행하시겠습니까?" 요청을 시도하고 실패하지 말고 — 먼저 물어보세요.

  3. DELETE 요청의 경우: 작업이 되돌릴 수 없음을 명시적으로 경고하고 어떤 데이터가 영구 삭제될지(사용자 레코드, 모든 세션, 모든 멤버십, 모든 관련 데이터) 정확히 나열하세요. 진행하기 전에 명시적인 확인을 요구하세요. 이 경고는 필수입니다 — 절대 건너뛰지 마십시오.

  4. 메타데이터 작업의 경우: 항상 어떤 메타데이터 유형을 사용하는지와 그 이유를 설명하세요(아래 메타데이터 유형 섹션 참조).


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 모드의 자연어 프롬프트의 경우, 먼저 확인하세요...

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

관련 스킬