API Keys

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

sk_ Private Key

Full read/write access to all resources

Create, modify, delete crawls
Manage webhooks and settings
Manage other API keys

Best for: Backend services, MCP connections, CI/CD pipelines

pk_ Public Key

Read-only access to crawl data

List and view crawls
Download crawl results
Cannot create or modify

Best for: Dashboards, monitoring, read-only integrations

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.

Key Permissions

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

Key Lifecycle

Key Expiration

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

Temporary Access

Set expiration for contractors or short-term projects

CI/CD Keys

Use short-lived keys and rotate regularly

Production Keys

Long-lived keys are fine with proper security

Usage Tracking

View last-used timestamps for each key

Revoking Keys

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

1 Go to Settings → API Keys

2 Find the key to revoke

3 Click the "Revoke" button

4 Confirm the action

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.

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

Back to Getting Started Review the initial setup process

Set up MCP integration Connect AI agents to Mulberry