Cosmicjs Roles and Permissions Guide | OpsBlu Docs

Cosmicjs Roles and Permissions Guide

Cosmic (formerly Cosmic JS) team roles -- Admin, Developer, Editor permissions and API key management for headless content delivery.

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

  1. Use read keys on client-side, write keys only on server-side
  2. Assign Developer role to frontend/backend engineers
  3. Use Editor role for content creators who should not touch content models
  4. Rotate API keys quarterly and store in environment variables
  5. Set up webhooks for content-change analytics tracking
Back to top