Cosmicjs User Management: Roles and Permissions | OpsBlu Docs

Cosmicjs User Management: Roles and Permissions

Manage user roles, permissions, and team access in CosmicJS — step-by-step admin guide.

This section covers user management, roles, and permissions for Cosmic JS (now Cosmic) and associated analytics tools. Cosmic is a headless CMS that provides API-first content management for modern web and mobile applications.

Overview

Cosmic provides comprehensive user management capabilities designed for development teams and content creators working with headless architecture. As a cloud-based headless CMS, Cosmic emphasizes flexible content delivery through APIs while offering robust collaboration features.

User management in Cosmic features:

  • Cloud-based administration through the Cosmic dashboard
  • Role-based access control with customizable permissions
  • API key management for secure programmatic access
  • Bucket-based organization for separating projects and teams
  • Read and Write API keys with different permission levels
  • Webhook support for real-time content notifications

Cosmic is ideal for JAMstack websites, mobile apps, and multi-channel content delivery requiring developer-friendly APIs.

Platform User Management

Accessing User Management

To manage users in Cosmic:

  1. Log in to your Cosmic dashboard at app.cosmicjs.com
  2. Select your Bucket (project)
  3. Navigate to Settings > Team Members or Users
  4. View current team members and their roles

User management is available on all plans, with team member limits varying by subscription tier.

Cosmic User Roles

Cosmic provides a flexible role system for team collaboration:

Owner

Bucket owners have complete control:

  • Full access to all bucket content and settings
  • Can manage all team members and permissions
  • Control over billing and subscription (for account level)
  • Can create, modify, and delete object types
  • Full access to all API keys
  • Can configure webhooks and integrations
  • Can delete the bucket
  • Access to all extensions and apps

When to use: Assigned to bucket creator and primary account holder.

Developer

Developers have technical access:

  • Can modify object types and schemas
  • Full access to API keys and documentation
  • Can configure webhooks
  • Cannot manage billing
  • Cannot delete the bucket
  • Can publish and unpublish content
  • Access to developer tools and extensions
  • Can modify bucket settings

When to use: Assign to software engineers integrating Cosmic.

Editor

Editors manage content publication:

  • Can create, edit, and publish content
  • Upload and manage media files
  • Cannot modify object types
  • Cannot access API keys
  • Cannot manage users or billing
  • Can preview content before publishing
  • Access to scheduling features
  • Can manage content in all locales

When to use: Assign to content managers and editorial team.

Contributor

Contributors create content with limitations:

  • Can create and edit their own content
  • Can save drafts
  • Cannot publish without approval
  • Cannot edit others' content
  • Limited media upload permissions
  • Cannot modify settings
  • Can view published content

When to use: Assign to content creators who need editorial oversight.

Bucket Management

Cosmic organizes content into Buckets (projects):

Creating Buckets

Buckets provide complete separation of:

  • Content and object types
  • Team members and permissions
  • API keys and webhooks
  • Billing (on some plans)

Use Cases for Multiple Buckets

  • Separate projects or websites
  • Development, staging, and production environments
  • Client-specific content management
  • Different brands or business units
  • Multi-tenant applications

Bucket-Level Permissions

Each bucket maintains its own:

  • Team member list
  • Role assignments
  • API keys
  • Webhook configurations

API Key Management

Cosmic uses API keys for all programmatic access:

API Key Types

Read Keys:

  • Public, read-only access to published content
  • Safe to use in client-side applications
  • Cannot modify or delete content
  • No rate limits on free plans
  • Included in all subscription tiers

Write Keys:

  • Full API access including content creation
  • Must be kept secret (server-side only)
  • Can create, update, delete content
  • Can modify object types
  • Higher rate limits

Managing API Keys

To create and manage API keys:

  1. Navigate to Settings > API Access
  2. View existing Read and Write keys
  3. Click Regenerate Key to rotate keys
  4. Copy keys to clipboard
  5. Store keys securely in environment variables

API Key Security Best Practices

  1. Never Commit Keys: Don't include in version control
  2. Use Environment Variables: Store in .env files or secret managers
  3. Separate Environments: Different keys for dev/staging/production
  4. Rotate Regularly: Change write keys every 90 days
  5. Use Read Keys Client-Side: Only use write keys server-side
  6. Monitor Usage: Review API usage analytics
  7. Revoke Compromised Keys: Regenerate immediately if exposed

Adding and Inviting Team Members

Inviting Users

To add a team member to a Cosmic bucket:

  1. Navigate to Settings > Team Members
  2. Click Invite Team Member
  3. Enter the user's email address
  4. Select appropriate role
  5. Optionally add a message
  6. Click Send Invitation

The invitee receives an email to:

  • Create a Cosmic account (if new)
  • Accept the bucket invitation
  • Access the shared bucket

Team Member Limits

User limits by plan:

  • Free Plan: 1 user per bucket
  • Startup Plan: Up to 5 users
  • Professional Plan: Up to 10 users
  • Enterprise Plan: Unlimited users

Removing Team Members

To remove a user:

  1. Go to Settings > Team Members
  2. Find the user to remove
  3. Click Remove or the delete icon
  4. Confirm the removal

Removed users lose immediate access. Their created content remains in the bucket.

Webhooks and Integrations

Cosmic supports webhooks for real-time content updates:

Creating Webhooks

  1. Navigate to Settings > Webhooks
  2. Click Add Webhook
  3. Enter webhook URL (your endpoint)
  4. Select triggering events:
    • Object created
    • Object edited
    • Object deleted
    • Media uploaded
  5. Save webhook

Webhook Security

  • Use HTTPS endpoints only
  • Implement signature verification
  • Validate webhook payloads
  • Monitor webhook delivery logs
  • Rotate webhook secrets periodically

Content Localization

Cosmic supports multi-language content:

Localization Features

  • Create content in multiple locales
  • Assign translators to specific languages
  • Locale-specific API queries
  • Fallback locale configuration
  • Automatic locale detection

Managing Translators

Assign team members to specific locales:

  • Limit access to translation workflows
  • Review translated content before publishing
  • Track translation progress

GraphQL API Access

Cosmic provides GraphQL in addition to REST:

GraphQL Features

  • Query multiple object types in one request
  • Precise field selection
  • Nested relationship queries
  • Real-time subscriptions (Enterprise)

GraphQL Security

  • Same API keys as REST API
  • Query depth limiting to prevent abuse
  • Rate limiting applies to GraphQL
  • Field-level permission controls

Security Best Practices

Access Control

  1. Use Appropriate Roles: Assign least privileged role necessary
  2. Limit Owners: Only 1-2 bucket owners
  3. Regular Audits: Review team quarterly
  4. Remove Inactive Users: Delete departed team members
  5. Separate Buckets: Use different buckets for different environments

API Security

  1. Protect Write Keys: Never expose in client-side code
  2. Environment Variables: Store keys securely
  3. Rate Limit Monitoring: Watch for unusual API activity
  4. Key Rotation: Change write keys every 90 days
  5. Scope Appropriately: Use read keys when possible

Webhook Security

  1. Verify Signatures: Implement webhook signature validation
  2. HTTPS Only: Don't use HTTP endpoints
  3. Payload Validation: Verify webhook data before processing
  4. Error Handling: Implement robust error handling
  5. Retry Logic: Handle webhook delivery failures

Common Issues and Solutions

Issue: API Key Not Working

Solution:

  • Verify key hasn't been regenerated
  • Check if using correct key type (read vs. write)
  • Ensure proper authentication header format
  • Verify bucket slug is correct
  • Check for API rate limiting

Issue: User Cannot Access Bucket

Solution:

  • Verify invitation was accepted
  • Check user has correct email address
  • Ensure user logged into correct Cosmic account
  • Review role permissions
  • Check if bucket was deleted or archived

Issue: Webhook Not Triggering

Solution:

  • Verify webhook URL is accessible publicly
  • Check webhook is enabled
  • Review webhook event configuration
  • Ensure endpoint returns 200 status
  • Check webhook delivery logs in Cosmic dashboard

Issue: Cannot Upload Media

Solution:

  • Check user role has media upload permissions
  • Verify file size within limits
  • Ensure file type is allowed
  • Check storage quota hasn't been exceeded
  • Review bucket settings for media restrictions

Issue: Content Not Appearing in API

Solution:

  • Verify content is published (not draft)
  • Check API query parameters
  • Ensure correct bucket slug
  • Verify API key permissions
  • Check if content type is configured correctly

Extension Ecosystem

Cosmic supports various extensions and integrations:

  • Image Optimization: Automatic image resizing and optimization
  • Search: Full-text search capabilities
  • Localization: Advanced multi-language features
  • Workflows: Custom content approval workflows
  • Backups: Automated bucket backups

Installing Extensions

  1. Navigate to Extensions in sidebar
  2. Browse available extensions
  3. Click Install on desired extension
  4. Configure extension settings
  5. Activate for your bucket

Deployment Webhooks

Trigger builds when content changes:

Setting Up Deploy Hooks

  1. Generate deploy hook from your hosting provider (Netlify, Vercel, etc.)
  2. Add as webhook in Cosmic
  3. Select object types to trigger deployments
  4. Test webhook delivery
  5. Monitor deployment logs

Analytics Tool Access

Google Analytics 4

Manage GA4 access in Admin > Account/Property Access Management:

  • Administrator: Full control over account settings and users
  • Editor: Can modify configurations and settings
  • Analyst: Can create reports and audiences, no configuration changes
  • Viewer: Read-only access to reports and data

Since Cosmic is headless:

  • Implement GA4 tracking in your frontend application
  • Use Cosmic webhooks to trigger analytics events
  • Track content performance through application analytics

Google Tag Manager

Manage GTM access in Admin > User Management:

  • Administrator: Full control over container and users
  • Publish: Can publish container changes to production
  • Approve: Can approve changes but not publish
  • Edit: Can edit tags and triggers but cannot approve or publish
  • Read: View-only access to container configuration

Implement GTM:

  • Add container code to your application
  • Track Cosmic content views and interactions
  • Use custom events for content engagement

Meta Business Manager

Manage access in Business Settings > People:

  • Admin: Full control over business settings and assets
  • Employee: Limited access based on assigned assets and permissions

Best Practices

  1. Use Buckets Strategically: Separate environments and projects into different buckets
  2. Protect Write API Keys: Never commit to version control or expose client-side
  3. Implement Read Keys: Use read-only keys for frontend applications
  4. Regular Key Rotation: Change write keys every 90 days minimum
  5. Monitor API Usage: Review usage analytics regularly
  6. Use Webhooks: Implement real-time content synchronization
  7. Version Control Object Types: Export and track object type schemas
  8. Regular Backups: Export bucket data periodically
  9. Document Team Structure: Maintain clear records of who has access
  10. Test in Development: Use separate buckets for development and production

Additional Resources

Nach oben