API Keys

Generate and manage API keys for programmatic access to M3 Forge workflows, data ingestion, and monitoring.

Overview

API keys enable external systems to interact with M3 Forge without user credentials. Use cases include:

• Workflow automation — Trigger workflow runs from CI/CD pipelines
• Data ingestion — Upload documents for processing from external applications
• Monitoring integration — Query metrics and logs for dashboards
• Webhook handlers — Respond to events from third-party systems
• Batch processing — Submit large volumes of documents for processing

API keys are workspace-scoped and inherit permissions from the user who creates them.

API Key Capabilities

Each API key provides access to:

Workflow Execution

Trigger workflow runs programmatically:

curl -X POST https://m3-forge.example.com/api/workflows/run \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "fraud-detection",
    "input": {
      "transaction_id": "txn_12345",
      "amount": 1250.00
    }
  }'

Data Upload

Upload documents to knowledge bases or workflow inputs:

curl -X POST https://m3-forge.example.com/api/documents/upload \
  -H "Authorization: Bearer sk_live_abc123..." \
  -F "file=@invoice.pdf" \
  -F "metadata={\"type\": \"invoice\", \"vendor\": \"ACME Corp\"}"

Query Execution History

Retrieve workflow run results:

curl -X GET https://m3-forge.example.com/api/runs/run_xyz789 \
  -H "Authorization: Bearer sk_live_abc123..."

Monitoring Metrics

Access metrics for external dashboards:

curl -X GET "https://m3-forge.example.com/api/metrics?start=2026-03-01&end=2026-03-19" \
  -H "Authorization: Bearer sk_live_abc123..."

Creating an API Key

API Key Format

M3 Forge API keys follow this format:

sk_live_abc123def456ghi789...

Components:

• sk — Indicates this is a secret key
• live — Environment (live for production, test for development)
• abc123... — Random identifier

Development keys use sk_test_ prefix for clarity.

Scopes

Scopes define what actions an API key can perform. Available scopes:

Scope Selection Best Practices

Follow the principle of least privilege:

• Single-purpose keys — Create separate keys for different systems (one for CI/CD, one for monitoring)
• Minimal scopes — Only grant necessary permissions
• Environment separation — Use test keys for development, live keys for production

Example: CI/CD Pipeline Key

Scopes: workflows.execute, runs.read
Reasoning: Pipeline needs to trigger deploys and check results, nothing else

Example: Monitoring Dashboard Key

Scopes: metrics.read, runs.read
Reasoning: Dashboard only displays data, never modifies

Example: Data Ingestion Key

Scopes: documents.upload, workflows.execute
Reasoning: Ingestion service uploads files and triggers processing workflows

Managing API Keys

Viewing API Keys

The API Keys page displays all keys in the workspace:

Columns:

• Name — Descriptive identifier
• Scopes — Abbreviated permission list
• Created — When key was generated
• Last Used — Most recent API request
• Expiration — Expiry date or “Never”
• Actions — Available operations

Rotating API Keys

To update a key without downtime:

This ensures zero downtime during key rotation.

Revoking API Keys

To permanently disable a key:

1. Click Revoke next to the key
2. Confirm revocation

Revoked keys:

• Stop working immediately
• Cannot be re-enabled
• Remain visible in audit logs

Revoke keys when:

• Key is compromised or exposed
• Associated application is decommissioned
• Key is no longer needed

Setting Expiration

For temporary access, set an expiration date:

1. When creating key, select Expiration date
2. Choose date (max 1 year from creation)
3. Key automatically stops working after expiration

Useful for:

• Contractor access with fixed term
• Temporary integrations
• Trial deployments

Using API Keys

HTTP Request Authentication

Include API key in the Authorization header:

curl https://m3-forge.example.com/api/workflows \
  -H "Authorization: Bearer sk_live_abc123..."

All API endpoints require authentication. Requests without valid keys return 401 Unauthorized.

tRPC Client Authentication

For TypeScript applications using tRPC:

import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@marie/api';
 
const client = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'https://m3-forge.example.com/trpc',
      headers: {
        Authorization: `Bearer sk_live_abc123...`,
      },
    }),
  ],
});
 
// Trigger a workflow
const result = await client.workflows.run.mutate({
  workflowId: 'fraud-detection',
  input: { transaction_id: 'txn_12345' },
});

Environment Variables

Store API keys in environment variables, never hardcode in source:

# .env file
M3_STUDIO_API_KEY=sk_live_abc123...

// Application code
const apiKey = process.env.M3_STUDIO_API_KEY;
if (!apiKey) {
  throw new Error('M3_STUDIO_API_KEY environment variable not set');
}

Secret Management

For production deployments, use a secret management system:

import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
 
const client = new SecretsManagerClient({ region: 'us-east-1' });
const response = await client.send(
  new GetSecretValueCommand({ SecretId: 'm3-forge-api-key' })
);
const apiKey = response.SecretString;

import vault from 'node-vault';
 
const client = vault({
  endpoint: 'https://vault.example.com',
  token: process.env.VAULT_TOKEN,
});
 
const result = await client.read('secret/data/m3-forge');
const apiKey = result.data.data.api_key;

import { SecretClient } from '@azure/keyvault-secrets';
import { DefaultAzureCredential } from '@azure/identity';
 
const client = new SecretClient(
  'https://my-vault.vault.azure.net',
  new DefaultAzureCredential()
);
 
const secret = await client.getSecret('m3-forge-api-key');
const apiKey = secret.value;

Rate Limiting

API keys can have rate limits to prevent abuse and control costs.

Setting Rate Limits

When creating or editing a key:

1. Enable Rate limiting
2. Set Requests per minute (e.g., 100)
3. Optionally set Burst allowance (e.g., 20 extra requests)

Requests exceeding the rate limit receive 429 Too Many Requests with a Retry-After header.

Rate Limit Headers

API responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710856800

• X-RateLimit-Limit — Total requests allowed per window
• X-RateLimit-Remaining — Requests remaining in current window
• X-RateLimit-Reset — Unix timestamp when window resets

Handling Rate Limits

Implement retry logic with exponential backoff:

async function callAPI(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      await sleep(retryAfter * 1000);
      continue;
    }
 
    return response;
  }
 
  throw new Error('Max retries exceeded');
}

Audit Logging

All API key usage is logged for security and compliance.

Logged Events

• Key creation — Who created key, with what scopes
• Key rotation — Old and new key identifiers
• Key revocation — Who revoked key and when
• API requests — Timestamp, endpoint, response status
• Failed authentication — Invalid or expired keys

Viewing Audit Logs

Navigate to Settings → Audit Logs and filter by:

• Event type — api_key.created, api_key.used, api_key.revoked
• Date range — Last 24 hours, 7 days, 30 days, custom
• API key name — Filter to specific key

Example log entries:

2026-03-19 14:32:15 | api_key.used | CI/CD Pipeline | POST /api/workflows/run | 200 OK
2026-03-19 14:30:42 | api_key.used | Monitoring | GET /api/metrics | 200 OK
2026-03-19 13:45:18 | api_key.failed_auth | (unknown) | POST /api/runs/cancel | 401 Unauthorized

Exporting Logs

For compliance or SIEM integration:

1. Apply filters to narrow results
2. Click Export
3. Choose format (CSV, JSON, CEF)
4. Download or send to webhook

Security Best Practices

Key Storage

• Never commit keys to Git — Use .gitignore for .env files
• Use secret management systems — AWS Secrets Manager, Vault, etc.
• Rotate keys quarterly — Update keys every 3 months
• Revoke unused keys — Clean up keys for decommissioned systems

Key Naming

Use descriptive names that indicate purpose:

Good:

• prod-data-ingestion-api
• staging-ci-cd-pipeline
• monitoring-dashboard-readonly

Poor:

• key-1
• test-key
• my-api-key

Scope Limitation

• Grant minimal scopes — Only what’s necessary for the use case
• Avoid wildcard scopes — Don’t use * unless truly needed
• Create separate keys — One per system/purpose

Monitoring

Set up alerts for:

• Unusual usage patterns — Sudden spike in requests
• Failed authentication attempts — Potential compromise
• New key creation — Unauthorized key generation
• Key approaching expiration — Reminder to rotate

Common Integration Patterns

CI/CD Deployment

Deploy workflows from GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy Workflow
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Deploy to M3 Forge
        env:
          M3_STUDIO_API_KEY: ${{ secrets.M3_STUDIO_API_KEY }}
        run: |
          curl -X POST https://m3-forge.example.com/api/workflows/deploy \
            -H "Authorization: Bearer $M3_STUDIO_API_KEY" \
            -F "workflow=@workflows/fraud-detection.json"

Batch Document Processing

Process uploaded files:

import requests
import os
 
API_KEY = os.environ['M3_STUDIO_API_KEY']
BASE_URL = 'https://m3-forge.example.com/api'
 
def process_documents(files):
    for file_path in files:
        # Upload document
        with open(file_path, 'rb') as f:
            upload_resp = requests.post(
                f'{BASE_URL}/documents/upload',
                headers={'Authorization': f'Bearer {API_KEY}'},
                files={'file': f}
            )
            doc_id = upload_resp.json()['id']
 
        # Trigger workflow
        run_resp = requests.post(
            f'{BASE_URL}/workflows/run',
            headers={'Authorization': f'Bearer {API_KEY}'},
            json={
                'workflow_id': 'invoice-extraction',
                'input': {'document_id': doc_id}
            }
        )
        print(f'Started run {run_resp.json()["run_id"]}')

Monitoring Integration

Export metrics to Prometheus:

import express from 'express';
import { register, Counter, Gauge } from 'prom-client';
 
const app = express();
 
const workflowRuns = new Counter({
  name: 'm3_forge_workflow_runs_total',
  help: 'Total workflow runs',
  labelNames: ['workflow', 'status'],
});
 
async function fetchMetrics() {
  const response = await fetch('https://m3-forge.example.com/api/metrics', {
    headers: { Authorization: `Bearer ${process.env.M3_STUDIO_API_KEY}` },
  });
 
  const data = await response.json();
 
  data.runs.forEach((run) => {
    workflowRuns.inc({ workflow: run.workflow, status: run.status });
  });
}
 
// Fetch metrics every minute
setInterval(fetchMetrics, 60000);
 
app.get('/metrics', (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(register.metrics());
});
 
app.listen(9090);

Troubleshooting

401 Unauthorized

Cause: Invalid, expired, or missing API key.

Solution:

1. Verify key format is correct (starts with sk_)
2. Check key hasn’t expired in API Keys settings
3. Confirm key hasn’t been revoked
4. Ensure Authorization: Bearer header is included

403 Forbidden

Cause: API key lacks required scope for operation.

Solution:

1. Check which scopes are needed for the endpoint
2. Edit API key to add missing scopes
3. Consider creating a new key with appropriate scopes

429 Too Many Requests

Cause: Exceeded rate limit.

Solution:

1. Implement exponential backoff retry logic
2. Increase rate limit in key settings
3. Distribute load across multiple API keys
4. Optimize requests to reduce volume

Key Not Working After Creation

Cause: Cached authentication state or typo in key.

Solution:

1. Copy key directly from API Keys page (avoid manual typing)
2. Wait 30 seconds for key to propagate
3. Verify no extra whitespace in key value
4. Test with a simple curl command first

Next Steps

• Review LLM connections to understand provider API keys
• Set up workspaces for environment isolation
• Configure users and roles to control who creates keys
• Integrate with workflows for automation
• Monitor API usage in monitoring dashboards