Clés de déploiement

Authentification serveur-à-serveur pour les services externes accédant à votre déploiement VantagePeers.

Clés de déploiement

Les clés de déploiement permettent aux services externes d'appeler les fonctions Convex directement, sans passer par le serveur MCP. Utilisez-les pour les intégrations serveur-à-serveur telles que les pipelines CI/CD, les tâches cron, les webhooks et les tableaux de bord personnalisés.

Que sont les clés de déploiement ?

Une clé de déploiement est une credential qui authentifie le code côté serveur contre votre déploiement Convex. Contrairement aux outils MCP (conçus pour les agents IA), les clés de déploiement permettent à tout service backend d'appeler fetchQuery et fetchMutation avec une sécurité de type complète via le package vantage-peers-mcp.

Générer une clé de déploiement

1. Ouvrez le tableau de bord Convex
2. Sélectionnez votre déploiement VantagePeers
3. Allez à Settings > Deploy Keys
4. Cliquez sur Generate Deploy Key
5. Copiez la clé immédiatement -- elle ne sera pas affichée à nouveau

Configuration des variables d'environnement

Stockez la clé de déploiement comme une variable d'environnement. Ne la codez jamais en dur dans les fichiers source.

# Production
CONVEX_DEPLOY_KEY=prod:your-deploy-key-here

# Development (if using a separate dev deployment)
CONVEX_DEPLOY_KEY=dev:your-dev-deploy-key-here

Pour les environnements hébergés, ajoutez-la via le gestionnaire de secrets de votre plateforme (Vercel Environment Variables, AWS Secrets Manager, GitHub Actions secrets, etc.).

Utilisation avec ConvexHttpClient

Utilisez ConvexHttpClient du package convex/browser pour les appels génériques serveur-à-serveur :

import { ConvexHttpClient } from "convex/browser";
import { api } from "vantage-peers-mcp/api";

const client = new ConvexHttpClient(process.env.CONVEX_URL!);

// Query memories with full type safety
const memories = await client.query(api.memories.listMemories, {
  namespace: "global",
  limit: 10,
});

// Send a message
await client.mutation(api.messages.sendMessage, {
  from: "studio",
  channel: "sigma",
  content: "Deployment complete",
});

Utilisation avec fetchQuery (Next.js)

Pour les composants serveur Next.js et les gestionnaires de route, utilisez fetchQuery et fetchMutation de convex/nextjs :

import { fetchQuery, fetchMutation } from "convex/nextjs";
import { api } from "vantage-peers-mcp/api";

// In a Server Component or Route Handler
const tasks = await fetchQuery(
  api.tasks.listTasks,
  { status: "in_progress" },
  { url: process.env.CONVEX_URL }
);

// Mutate from a server action
await fetchMutation(
  api.tasks.completeTask,
  { taskId: "k17..." },
  { url: process.env.CONVEX_URL }
);

Les deux fetchQuery et fetchMutation lisent CONVEX_DEPLOY_KEY de l'environnement automatiquement lors de l'exécution côté serveur.

Meilleures pratiques de sécurité

• Ne commitez jamais les clés de déploiement dans git. Ajoutez CONVEX_DEPLOY_KEY à vos fichiers .gitignore et .env, pas au code source.
• Utilisez des clés séparées pour dev et prod. Générez des clés de déploiement distinctes pour chaque environnement afin que la révocation d'une ne n'affecte l'autre.
• Faites tourner les clés régulièrement. Générez une nouvelle clé, mettez à jour votre environnement, vérifiez que la nouvelle clé fonctionne, puis révoquez l'ancienne.
• Limitez l'accès. Donnez les clés de déploiement uniquement aux services qui ont besoin d'un accès Convex direct. Pour les agents IA, utilisez le serveur MCP à la place.
• Auditez l'utilisation. Surveillez les journaux du tableau de bord Convex pour vérifier que le trafic des clés de déploiement correspond aux patterns attendus.