Cosmic (formerly Cosmic JS) is a headless CMS with a role-based team system. Permissions affect dashboard access and API capabilities.
Cosmic Role Model
| Role | Manage Team | Manage Bucket Settings | Create/Edit Content | Delete Content | Manage Object Types | API Keys |
|---|---|---|---|---|---|---|
| Admin | Yes | Yes | Yes | Yes | Yes | Full |
| Developer | No | Partial | Yes | Yes | Yes | Read |
| Editor | No | No | Yes | No | No | Read |
Admin
Full control over the Cosmic Bucket including team management, billing, API key creation, webhooks, and all content operations.
Developer
Can manage Object Types (content models), create and edit Objects, and access the API. Cannot manage team members or billing.
Editor
Can create and edit content Objects within existing Object Types. Cannot modify content models or access technical settings.
API Key Scopes
Cosmic uses read and write API keys:
# Read key (safe for client-side, fetches published content)
curl "https://api.cosmicjs.com/v3/buckets/{bucket-slug}/objects" \
-H "Authorization: Bearer YOUR_READ_KEY"
# Write key (server-side only, creates/updates content)
curl -X POST "https://api.cosmicjs.com/v3/buckets/{bucket-slug}/objects" \
-H "Authorization: Bearer YOUR_WRITE_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "New Page", "type": "pages", "content": "..."}'
Analytics-Relevant Permissions
Since Cosmic is headless, analytics scripts live in your frontend. Cosmic webhooks can trigger analytics events:
// Webhook configuration via Dashboard > Settings > Webhooks
// Fires on object.created, object.edited, object.deleted
// Use to sync content events to your analytics pipeline
Custom Roles
Cosmic does not support custom roles beyond Admin, Developer, and Editor. Use separate Buckets for fine-grained project isolation.
Best Practices
- Use read keys on client-side, write keys only on server-side
- Assign Developer role to frontend/backend engineers
- Use Editor role for content creators who should not touch content models
- Rotate API keys quarterly and store in environment variables
- Set up webhooks for content-change analytics tracking