API Keys
Generate API keys, configure scopes, implement rotation policies, and maintain security best practices
API Keys
TeamAPI keys allow programmatic access to MongoDash for automation, integrations, and external applications.
What are API Keys?
API keys are secret tokens that authenticate requests to the MongoDash API without requiring username and password credentials. They enable:
- Automation - Scheduled scripts for data operations
- Integrations - Connect MongoDash to other tools and platforms
- CI/CD Pipelines - Automated testing and deployment workflows
- Custom Applications - Build tools on top of MongoDash data
API keys provide programmatic access to your workspace. Treat them like passwords and never commit them to version control.
Understanding API Key Scopes
API keys support granular scopes that limit what actions the key can perform. This follows the principle of least privilege.
Available Scopes
Read Scopes
- read:connections - View connection details
- read:collections - List databases and collections
- read:documents - Query and read document data
- read:queries - View saved queries
- read:dashboards - Access dashboard definitions and data
Write Scopes
- write:documents - Insert and update documents
- write:queries - Create and modify saved queries
- write:dashboards - Create and edit dashboards
Admin Scopes
- admin:connections - Create, edit, and delete connections
- admin:members - Manage workspace members
- admin:workspace - Modify workspace settings
Scope Best Practices
- Grant only the scopes needed for the specific use case
- Use read-only scopes for reporting and analytics
- Limit admin scopes to trusted automation only
- Create separate keys for different integrations
Creating API Keys
Navigate to API Settings Click your profile picture, select Account Settings, then navigate to the API Keys tab.
Create New Key Click Create API Key to open the configuration dialog.
Name Your Key Enter a descriptive name that indicates the key's purpose:
- Good: "CI Pipeline - Read Only", "Analytics Integration", "Weekly Report Script"
- Avoid: "API Key 1", "Test", "Temporary"
Use descriptive names to easily identify and audit keys later.
Select Scopes Choose the minimum scopes required for your use case. You can always create a new key with broader scopes if needed.
Set Expiration Choose an expiration period:
- 30 days - Short-term testing and experiments
- 90 days - Quarterly rotation for production use
- 1 year - Long-lived integrations with annual rotation
- Never - Only for critical systems with manual rotation policies
Non-expiring keys pose security risks. Set a reasonable expiration and plan for key rotation.
Generate Key Click Create Key to generate the API key. The key will only be displayed once.
Copy and Store Copy the API key immediately and store it securely in a password manager or secrets management system.
This is the only time the full API key will be displayed. If you lose it, you'll need to create a new one.
Using API Keys
Include your API key in requests using the Authorization header:
curl -H "Authorization: Bearer md_key_abc123..." \
https://api.mongodash.app/v1/workspaces/my-workspace/collectionsAuthentication Headers
Authorization: Bearer YOUR_API_KEYExample Requests
List Collections
curl -X GET \
-H "Authorization: Bearer md_key_abc123..." \
https://api.mongodash.app/v1/workspaces/my-workspace/collectionsQuery Documents
curl -X POST \
-H "Authorization: Bearer md_key_abc123..." \
-H "Content-Type: application/json" \
-d '{"filter": {"status": "active"}}' \
https://api.mongodash.app/v1/workspaces/my-workspace/collections/users/querySee the API Integration guide for complete API documentation and examples.
Managing API Keys
Viewing Active Keys
Your API Keys page shows all active keys with:
- Name - Descriptive identifier
- Scopes - Granted permissions
- Last Used - Timestamp of most recent API call
- Created - When the key was generated
- Expires - Expiration date (if set)
Monitoring Key Usage
Click on any API key to view detailed usage statistics:
- Request count by endpoint
- Success vs. error rates
- Geographic distribution of requests
- Recent activity timeline
Review key usage regularly to identify unused keys that should be revoked.
Revoking API Keys
To revoke an API key immediately:
Select Key Click the API key you want to revoke from your API Keys list.
Revoke Key Click Revoke Key and confirm the action.
Revoking a key immediately invalidates it. Any applications using this key will lose access.
Update Applications Update any applications or scripts using the revoked key before they fail.
API Key Rotation
Regular key rotation reduces the risk of compromised credentials.
Rotation Strategy
Create New Key Generate a new API key with the same scopes as the key you're rotating.
Update Applications Deploy the new key to all applications and scripts using the old key.
Monitor Old Key Keep the old key active briefly to ensure all systems have been updated.
Revoke Old Key Once the old key shows no recent usage, revoke it to complete the rotation.
Recommended Rotation Schedules
- Critical Production Keys - Every 90 days
- Standard Integration Keys - Every 6 months
- Development/Testing Keys - Every 30 days or as needed
- Compromised Keys - Immediately
Security Best Practices
Never Commit Keys to Version Control
API keys should never appear in:
- Git repositories
- Configuration files committed to source control
- Log files or error messages
- Client-side code or JavaScript bundles
Use environment variables or secrets management systems instead:
# .env file (add to .gitignore)
MONGODASH_API_KEY=md_key_abc123...
# In your application
const apiKey = process.env.MONGODASH_API_KEYUse Environment-Specific Keys
Create separate API keys for each environment:
- Development - Limited scopes, short expiration
- Staging - Production-like scopes, separate from prod key
- Production - Full required scopes, longer expiration, strict monitoring
Store Keys Securely
Use dedicated secrets management:
- HashiCorp Vault - Enterprise secrets management
- AWS Secrets Manager - Cloud-native secrets storage
- Azure Key Vault - Microsoft cloud secrets
- Password Managers - For individual developer keys
Monitor for Compromised Keys
Watch for signs of compromised API keys:
- Unexpected usage patterns
- Requests from unknown IP addresses
- High error rates or failed authentication attempts
- Usage during off-hours or from unusual geographic locations
If you suspect a key is compromised, revoke it immediately and generate a new one.
IP Allowlisting
BusinessRestrict API key usage to specific IP addresses:
- Edit an API key
- Enable IP Allowlist
- Add trusted IP addresses or CIDR ranges
- Save changes
Requests from non-allowlisted IPs will be rejected even with a valid key.
Workspace API Key Management
BusinessWorkspace Owners can view and manage all API keys created by workspace members:
- View all active keys across the workspace
- Revoke keys created by other members
- Set workspace-wide key expiration policies
- Receive alerts for suspicious API activity
Rate Limits
API keys are subject to rate limits based on your plan:
| Plan | Requests per Minute | Requests per Hour |
|---|---|---|
| Team | 60 | 1,000 |
| Business | 300 | 10,000 |
| Enterprise | Custom | Custom |
Rate limits are per API key. Distribute load across multiple keys if needed, but avoid creating excessive keys.
What's Next?
- API Integration - Complete API documentation and examples
- Session Management - Manage active user sessions
- Audit Logs - Track API key usage and security events