Mulberry | Docs
Home

API Keys

API keys authenticate requests to the Mulberry API and MCP server. This guide covers creating keys, understanding permissions, and managing key lifecycle.

Key Types

Mulberry supports two types of API keys:

Private Keys (sk_)

  • Full read/write access
  • Can create, modify, and delete crawls
  • Can manage webhooks and settings
  • Prefixed with sk_ (secret key)

Use private keys for:

  • Backend services that create crawls
  • MCP connections for AI agents
  • Automation and CI/CD pipelines

Public Keys (pk_)

  • Read-only access
  • Can list and view crawls
  • Cannot create or modify data
  • Prefixed with pk_ (public key)

Use public keys for:

  • Dashboards and monitoring tools
  • Read-only integrations
  • Sharing access without write permissions

Creating API Keys

Via Dashboard

  1. Navigate to Settings → API Keys
  2. Click "Create API Key"
  3. Select key type (Private or Public)
  4. Enter a descriptive name (e.g., "Production Backend")
  5. Optionally set an expiration date
  6. Click "Create"
  7. Copy the key immediately
Important: The full API key is only shown once at creation. If you lose it, you'll need to create a new key.

Via API

curl -X POST \
  -H "Authorization: Bearer sk_existing_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Key",
    "type": "private",
    "expires_at": "2025-01-01T00:00:00Z"
  }' \
  https://your-server/api/api_keys

Key Permissions

Action Private (sk_) Public (pk_)
List crawls ✓ ✓
View crawl details ✓ ✓
Download results ✓ ✓
Create crawls ✓ ✗
Cancel crawls ✓ ✗
Manage webhooks ✓ ✗
Manage API keys ✓ ✗

Key Expiration

API keys can optionally have an expiration date. After expiration, the key becomes invalid and requests using it will fail.

Recommended practices:

  • Set expiration for temporary or contractor access
  • Use short-lived keys for CI/CD (rotate regularly)
  • Long-lived keys are acceptable for production services with proper security

Revoking Keys

Revoke a key immediately if it's compromised or no longer needed:

Via Dashboard

  1. Go to Settings → API Keys
  2. Find the key to revoke
  3. Click the "Revoke" button
  4. Confirm the action

Via API

curl -X DELETE \
  -H "Authorization: Bearer sk_admin_key" \
  https://your-server/api/api_keys/key_id_to_revoke
Warning: Revoking a key is immediate and permanent. Any services using the key will lose access instantly.

Key Rotation

Regularly rotating keys is a security best practice. Here's a safe rotation process:

  1. Create a new API key with the same permissions
  2. Update your services to use the new key
  3. Verify services work with the new key
  4. Revoke the old key
Tip: Automate key rotation in your deployment pipeline. Create a new key, deploy with it, then revoke the old one.

Last Used Tracking

Mulberry tracks when each key was last used. This helps identify:

  • Unused keys that can be safely revoked
  • Which services are actively using which keys
  • Potential unauthorized access patterns

View last-used timestamps in Settings → API Keys.

Security Best Practices

  • Never commit keys to version control - Use environment variables or secrets management
  • Use the principle of least privilege - Use public keys when write access isn't needed
  • Set expiration dates - Especially for temporary access
  • Rotate keys periodically - Monthly rotation is a good baseline
  • Monitor key usage - Review last-used dates regularly
  • Revoke unused keys - If a key hasn't been used in months, revoke it

Troubleshooting

401 Unauthorized

Check that:

  • The key is correctly formatted in the Authorization header
  • The key hasn't been revoked
  • The key hasn't expired

403 Forbidden

The key is valid but lacks permission for the action. Check:

  • Are you using a public key (pk_) for a write operation?
  • Does the key have the required scope?

Next Steps