Learn how to securely manage your Metorial and AI SDK credentials in your applications.

Never Hardcode API Keys

Never put API keys directly in your code:

// ❌ NEVER DO THIS
const metorial = new Metorial({
  apiKey: 'met_abc123xyz'
});

Instead, use environment variables:

// ✅ DO THIS
const metorial = new Metorial({
  apiKey: process.env.METORIAL_API_KEY!
});

Setting Up Environment Variables

Create a .env.local file in your project root:

# Metorial Configuration
METORIAL_API_KEY=your-metorial-api-key
METORIAL_DEPLOYMENT_ID=your-deployment-id

# AI Provider (example for OpenAI)
OPENAI_API_KEY=your-openai-api-key

Important: Add .env.local to your .gitignore:

# .gitignore
.env.local
.env*.local

Using Environment Variables

Access them in your code:

import { Metorial } from 'metorial';

const metorial = new Metorial({
  apiKey: process.env.METORIAL_API_KEY!
});

await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: [process.env.METORIAL_DEPLOYMENT_ID!] },
  async session => {
    // Your code here
  }
);

Production Deployment

Vercel

1. Go to your project settings
2. Navigate to "Environment Variables"
3. Add your keys with appropriate scopes (Production, Preview, Development)

Other Platforms

Consult your platform's documentation for managing environment variables:

• Netlify: Site settings > Environment variables
• Railway: Project settings > Variables
• AWS: Use AWS Secrets Manager or Parameter Store
• Docker: Pass via -e flag or docker-compose.yml

Security Best Practices

1. Rotate keys regularly: Generate new API keys every few months
2. Use separate keys per environment: Different keys for dev, staging, and production
3. Limit key permissions: Only grant necessary access
4. Monitor usage: Check your Metorial dashboard for unusual activity
5. Never log keys: Avoid logging environment variables
6. Server-side only: Never expose API keys to client-side code

Client-Side vs Server-Side

Metorial API keys should only be used server-side:

// ✅ Server-side (Next.js API Route)
export async function POST(req: Request) {
  const metorial = new Metorial({
    apiKey: process.env.METORIAL_API_KEY! // Safe - runs on server
  });
  // ...
}

// ❌ Client-side (React Component)
function MyComponent() {
  const metorial = new Metorial({
    apiKey: process.env.NEXT_PUBLIC_METORIAL_API_KEY // NEVER DO THIS
  });
  // ...
}

Revoking Compromised Keys

If you suspect a key has been compromised:

1. Immediately revoke it in your Metorial dashboard
2. Generate a new key
3. Update your environment variables
4. Redeploy your application
5. Review recent API usage for suspicious activity