Communitygithub.com

deangilmoreremix/videoremix.vip2

Explorador e executor da API REST do Clerk Backend. Navegue por tags, inspecione esquemas de endpoints e execute requisições autenticadas. Use para listar usuários, gerenciar organizações ou chamar qualquer endpoint da API Clerk.

O que é videoremix.vip2?

Esta skill permite que agentes de IA interajam diretamente com a API Backend do Clerk, oferecendo um explorador e executor completo para desenvolvedores. Ela suporta operações comuns como listar usuários, criar organizações, convidar membros e gerenciar metadados, utilizando templates prontos para comandos `curl` ou o SDK TypeScript (`@clerk/nextjs` ou `@clerk/backend`). Além do caminho rápido para operações frequentes, a skill fornece uma referência completa de endpoints para usuários e organizações, incluindo parâmetros de consulta, corpos de requisição e detalhes de resposta. Sua principal força está na segurança integrada: ela impõe verificações obrigatórias antes de qualquer operação de escrita, como validar a chave secreta (`CLERK_SECRET_KEY`), confirmar escopos (`CLERK_BAPI_SCOPES`), exigir confirmação explícita para exclusões irreversíveis e explicar os três tipos de metadados (público, privado e inseguro) antes de modificar dados de usuário. Também documenta limites de taxa, armadilhas de sobrescrita de metadados (que substituem, não mesclam) e modos de uso (ajuda, navegação, execução e inspeção de esquemas). A skill é projetada para plataformas como Claude Code, Cursor e Codex, utilizando comandos `curl` diretos para chamadas de API.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Contexto de Opções

Prompt do Usuário: $ARGUMENTS

CRÍTICO: Verificações obrigatórias ANTES de cada requisição de escrita

Antes de QUALQUER POST / PATCH / PUT / DELETE, você DEVE fazer TODAS as seguintes verificações na sua resposta:

  1. Verificar CLERK_SECRET_KEY — certifique-se de que está definida:

    echo $CLERK_SECRET_KEY | head -c 10
    

    Se estiver vazia, pare e pergunte ao usuário. Não prossiga sem uma chave válida.

  2. Verificar CLERK_BAPI_SCOPES — execute:

    echo $CLERK_BAPI_SCOPES
    

    Inspecione a saída. Se os escopos estiverem faltando ou não incluírem a permissão de escrita necessária, informe ao usuário: "Esta é uma operação de escrita e seus escopos atuais podem não permiti-la. Executar novamente com --admin para ignorar?" NÃO tente a requisição e falhe — pergunte primeiro.

  3. Para requisições DELETE: avise explicitamente que a ação é IRREVERSÍVEL e liste exatamente quais dados serão permanentemente destruídos (registro do usuário, todas as sessões, todas as associações, todos os dados associados). Exija confirmação explícita antes de prosseguir. Este aviso é OBRIGATÓRIO — nunca o pule.

  4. Para operações de metadados: sempre explique qual tipo de metadado está sendo usado e por quê (veja a seção Tipos de Metadados abaixo).


CAMINHO RÁPIDO: Operações comuns (use diretamente, sem buscar especificações)

Para as operações abaixo, pule a busca de especificações e execute imediatamente usando estes modelos exatos. Substitua $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL conforme necessário do contexto do usuário.

Criar organização + convidar membro (duas etapas)

# Etapa 1 — Criar organização
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))"

# Etapa 2 — Extrair ID da organização
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Etapa 3 — Convidar membro com função
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))"

Funções: use "org:admin" ou "org:member" (sempre prefixado com org:).

Equivalente SDK (para projetos Next.js / TypeScript com @clerk/nextjs ou @clerk/backend)

import { clerkClient } from '@clerk/nextjs/server'
// OU se estiver usando @clerk/backend diretamente:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

// Etapa 1: Criar organização
const org = await clerkClient.organizations.createOrganization({
  name: 'Acme Corp',
  createdBy: userId,  // obrigatório — o ID do usuário que está criando a org
})

// Etapa 2: Convidar membro para a org
const invitation = await clerkClient.organizations.createOrganizationInvitation({
  organizationId: org.id,
  emailAddress: '[email protected]',
  role: 'org:admin',  // ou 'org:member'
})

Atualizar metadados do usuário

Sempre explique os três tipos de metadados antes de perguntar qual usar:

TipoCampoLegível porEditável porUso para
Públicopublic_metadataCliente + ServidorApenas servidorPlano, funções, flags de recursos que o frontend lê
Privadoprivate_metadataApenas servidorApenas servidorIDs Stripe, flags de conformidade, identificadores internos
Insegurounsafe_metadataCliente + ServidorCliente + ServidorEstado de IU efêmero, etapas de onboarding (editável pelo cliente — evite dados sensíveis)

Para plan: 'pro' e onboarded: true — use public_metadata (legível pelo frontend, editável pelo servidor):

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'Usuário atualizado {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')"

Equivalente SDK:

import { clerkClient } from '@clerk/nextjs/server'
// OU: import { createClerkClient } from '@clerk/backend'

await clerkClient.users.updateUser(userId, {
  publicMetadata: { plan: 'pro', onboarded: true },   // legível pelo cliente, editável apenas pelo servidor
  // privateMetadata: { stripeId: 'cus_xxx' },         // leitura e escrita apenas pelo servidor
  // unsafeMetadata: { step: 'welcome' },              // editável pelo cliente, evite dados sensíveis
})

Nota: A API REST usa snake_case (public_metadata). O SDK usa camelCase (publicMetadata).

Listar usuários (últimos 7 dias)

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'Encontrados {len(data)} usuários:')
    for u in data:
        print(f'  {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"sem email\")}')
else:
    print(json.dumps(data, indent=2))
"

Excluir usuário (confirmação necessária)

# EXECUTAR APENAS após confirmação explícita do usuário
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'Excluído: {d}')"

Referência Completa de Endpoints da Clerk Backend API

URL Base: https://api.clerk.com/v1 Autenticação: Authorization: Bearer $CLERK_SECRET_KEY em cada requisição.

Usuários

Listar usuários

GET /v1/users
Parâmetros de consulta: limit (máx. 500, padrão 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 (intervalo ISO 8601: gt:TIMESTAMP ou lt:TIMESTAMP em ms Unix)
Retorna: array de objetos User

Obter usuário

GET /v1/users/{user_id}
Retorna: objeto User

Atualizar usuário

PATCH /v1/users/{user_id}
Corpo (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }

Excluir usuário — IRREVERSÍVEL

DELETE /v1/users/{user_id}
Destrói: registro do usuário, todas as sessões, todas as associações, todos os dados associados
Retorna: { id, object, deleted: true }

Sempre avise o usuário que isso é permanente e confirme antes de prosseguir.

Organizações

Criar organização

POST /v1/organizations
Corpo: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Retorna: objeto Organization com { id, name, slug, ... }

Listar organizações

GET /v1/organizations
Parâmetros de consulta: limit, offset, query, order_by

Convidar membro

POST /v1/organizations/{organization_id}/invitations
Corpo: { email_address: string, role: string ("org:admin" ou "org:member"), public_metadata?, private_metadata? }
Retorna: objeto OrganizationInvitation

Como executar requisições

SEMPRE execute requisições com comandos curl diretos. Use os scripts de extração de especificações (api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh) para descobrir endpoints, mas faça chamadas de API reais com curl. NÃO use scripts/execute-request.sh — é um auxiliar de desenvolvimento local, não para uso do agente.

Modelo para requisições GET:

curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY"

Modelo para requisições 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}'

Modelo para requisições DELETE:

curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY"

Após obter a resposta: Analise e exiba claramente. Use python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" para formatar JSON. Extraia campos-chave (id, email, nome, etc.) e resuma para o usuário.


Contexto de especificações da API

Antes de fazer qualquer coisa fora do CAMINHO RÁPIDO, busque as versões e tags disponíveis da especificação executando:

bash scripts/api-specs-context.sh

Use a saída para determinar a versão mais recente e as tags disponíveis.

Cache: Se você já buscou o contexto da especificação anteriormente nesta conversa, NÃO o busque novamente. Reutilize a versão e as tags da chamada anterior.


Regras

  • Para operações comuns (listar usuários, criar organização, convidar, atualizar metadados, excluir usuário): use o CAMINHO RÁPIDO acima — NÃO busque especificações primeiro.
  • Sempre ignore endpoints/esquemas relacionados a platform.
  • Sempre confirme antes de realizar requisições de escrita (POST/PUT/PATCH/DELETE).
  • Para operações DELETE, sempre avise o usuário que a ação é irreversível e mencione quais dados serão perdidos (registro do usuário, sessões, associações). Este aviso é OBRIGATÓRIO — nunca o pule.
  • Para operações de escrita (POST/PUT/PATCH/DELETE), verifique CLERK_BAPI_SCOPES antes de tentar a requisição. Se estiverem faltando ou forem insuficientes, pergunte ao usuário antecipadamente. NÃO tente e falhe — pergunte antes de executar. Esta verificação é OBRIGATÓRIA.
  • Para operações de metadados, sempre explique todos os três tipos (público, privado, inseguro) e recomende o apropriado.
  • Paginação: sempre use limit + offset e mencione que os resultados podem ser paginados para grandes conjuntos de dados.
  • Use comandos curl diretos para todas as chamadas de API — nunca use scripts/execute-request.sh.

Limites de Taxa e Armadilhas

Limites de Taxa

AmbienteLimite
Produção1.000 requisições / 10 segundos
Desenvolvimento100 requisições / 10 segundos
Convites únicos100 / hora
Convites em massa25 / hora
Convites de organização250 / hora
Criação de login na API Frontend5 / 10 segundos
Tentativas de login na API Frontend3 / 10 segundos
Máx. de usuários por página na listagem500

currentUser() faz uma chamada de API real que conta contra os limites de taxa. Use auth() apenas para as claims da sessão — lê do token sem uma chamada de API.

Sobrescrita de Metadados (Não Mesclagem)

updateUser({ publicMetadata: { role: 'admin' } }) SUBSTITUI todos os metadados públicos, não mescla. Para adicionar um campo sem perder dados existentes: leia primeiro, espalhe, depois escreva.

Errado:

await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })

Isso EXCLUI todos os outros campos publicMetadata.

Correto:

const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
  publicMetadata: { ...user.publicMetadata, newField: 'value' },
})

Modos

Determine o modo ativo com base no prompt do usuário em Contexto de Opções:

ModoGatilhoComportamento
helpPrompt está vazio, ou contém apenas help / -h / --helpImprimir exemplos de uso (etapa 0)
browsePrompt é tags, ou um nome de tag (ex. Users)Listar todas as tags ou endpoints para uma tag
executeEndpoint específico (ex. GET /users) ou ação em linguagem natural (ex. "obter usuário john_doe")Pesquisar endpoint, executar requisição
detailEndpoint + help / -h / --help (ex. GET /users help)Mostrar esquema do endpoint, não executar

Sua Tarefa

Use a VERSÃO MAIS RECENTE do Contexto de especificações da API por padrão. Se o usuário especificar uma versão diferente (ex. --version 2024-10-01), use essa versão.

Determine o modo ativo, depois siga as etapas aplicáveis abaixo.


0. Imprimir uso

Modos: apenas help — Pule para browse, execute e detail.

Imprima os seguintes exemplos para o usuário textualmente:

Navegar
  /clerk-backend-api tags                         — listar todas as tags
  /clerk-backend-api Users                        — navegar pelos endpoints da tag Users
  /clerk-backend-api Users version 2025-11-10.yml — navegar usando uma versão diferente

Executar
  /clerk-backend-api GET /users             — buscar todos os usuários
  /clerk-backend-api get user john_doe      — linguagem natural também funciona
  /clerk-backend-api POST /invitations      — criar um convite

Inspecionar
  /clerk-backend-api GET /users help        — mostrar esquema do endpoint sem executar
  /clerk-backend-api POST /invitations -h   — ver detalhes de requisição/resposta

Opções
  --admin                            — ignorar restrições de escopo para escrita/exclusão
  --version [date], version [date]   — usar uma versão específica da especificação
  --help, -h, help                   — inspecionar endpoint em vez de executar

Pare aqui.


1. Buscar tags

Modos: browse (quando o prompt é tags ou nenhuma tag especificada) — Pule para help, execute e detail.

Se estiver usando uma versão não recente, busque tags para essa versão:

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js

Caso contrário, use as TAGS já no Contexto de especificações da API.

Compartilhe as tags em uma tabela e peça ao usuário para selecionar uma consulta.


2. Buscar endpoints da tag

Modos: browse (quando um nome de tag é fornecido) — Pule para help, execute e detail.

Busque todos os endpoints para a tag identificada:

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"

Compartilhe os resultados (endpoints, esquemas, parâmetros) com o usuário.


3. Buscar detalhes do endpoint

Modos: execute, detail — Pule para help e browse.

Para prompts em linguagem natural no modo execute, primeiro verifique se a ação corresponde a uma operação do CAMINHO RÁPIDO. Se sim, execute usando o modelo do CAMINHO RÁPIDO. Caso contrário, busque as especificações e determine o endpoint mais relevante.

[continuação omitida para tradução]

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

Habilidades Relacionadas