Adding & Removing Users on Cosmic JS

Adding & Removing Users on Cosmic JS — setup, configuration, and best practices for CosmicJS.

Cosmic (formerly Cosmic JS) is a headless CMS with a cloud dashboard and a comprehensive REST API. Team members are managed per-project (called "Buckets") through the dashboard at app.cosmicjs.com or the Cosmic API. User limits depend on your plan tier.

Adding Users via the Dashboard

Inviting Team Members

Log in to app.cosmicjs.com
Select the target Bucket (project)
Navigate to Bucket Settings > Team (gear icon in the sidebar)
Click Add Team Member
Enter the user's email address
Select a role:
- Admin -- Full access to all content, settings, media, webhooks, and team management
- Developer -- Access to content, Object Types, media, webhooks, and API settings; cannot manage team or billing
- Editor -- Create and edit Objects (content); no access to settings, Object Types, or team management
- Contributor -- Create Objects only; cannot edit existing content or delete anything
Click Send Invite

The invited user receives an email to join the Bucket. They must create a Cosmic account or log in with an existing one.

Plan-Based User Limits

Plan	Team Members per Bucket
Free	1
Pro	3
Team	5
Enterprise	Unlimited

Adding Users via the Cosmic API

Cosmic provides a full REST API for user and team management:

# Invite a team member via the API
curl -X POST "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/team" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jsmith@example.com",
    "role": "editor"
  }'

# List all team members
curl -s "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/team" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN" | python3 -m json.tool

# Get a specific team member's details
curl -s "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/team/MEMBER_ID" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN"

Using the Cosmic JavaScript SDK

// Install: npm install @cosmicjs/sdk

const { createBucketClient } = require('@cosmicjs/sdk');

const cosmic = createBucketClient({
  bucketSlug: 'your-bucket-slug',
  readKey: process.env.COSMIC_READ_KEY,
  writeKey: process.env.COSMIC_WRITE_KEY,
});

// Invite a new team member
async function inviteUser(email, role) {
  try {
    const response = await cosmic.team.addMember({
      email: email,
      role: role, // 'admin', 'developer', 'editor', 'contributor'
    });
    console.log(`Invited: ${email} as ${role}`);
    return response;
  } catch (err) {
    console.error(`Failed to invite ${email}:`, err.message);
  }
}

// List all team members
async function listTeam() {
  const { members } = await cosmic.team.getMembers();
  members.forEach(m => {
    console.log(`${m.email} - ${m.role} - Last login: ${m.last_login || 'never'}`);
  });
}

inviteUser('jsmith@example.com', 'editor');

Updating a User's Role

# Change a team member's role
curl -X PATCH "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/team/MEMBER_ID" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "developer"}'

Removing Users

Removing via the Dashboard

Go to Bucket Settings > Team
Find the team member
Click the Remove button (or trash icon) next to their name
Confirm the removal

Removing via the API

# Remove a team member
curl -X DELETE "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/team/MEMBER_ID" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN"

What Happens to Their Content

When you remove a Cosmic team member:

All Objects (content) they created remain intact -- published, draft, and scheduled content is unaffected
Content delivered via the API continues without interruption
The created_by metadata on Objects retains the user's ID
Media files uploaded by the user remain in the Bucket
The removed user immediately loses dashboard and API access to the Bucket
Their Cosmic account still exists -- they just lose access to your Bucket
If the user was the Bucket owner, ownership must be transferred before removal

Transferring Bucket Ownership

# Transfer Bucket ownership to another admin
curl -X POST "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/transfer" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "newowner@example.com"}'

Bulk User Management

Bulk Invite Script

#!/bin/bash
# bulk-invite.sh -- Invite multiple users from a file

BUCKET_SLUG="your-bucket-slug"
BUCKET_TOKEN="your-bucket-write-key"

while IFS=',' read -r email role; do
  response=$(curl -s -o /dev/null -w "%{http_code}" \
    -X POST "https://api.cosmicjs.com/v3/buckets/$BUCKET_SLUG/team" \
    -H "Authorization: Bearer $BUCKET_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$email\", \"role\": \"$role\"}")

  echo "$email ($role): HTTP $response"
done < invites.csv

Audit Team Members Across Multiple Buckets

#!/usr/bin/env python3
"""audit_cosmic_teams.py -- List team members across all Buckets."""

import requests
import os

API_TOKEN = os.environ["COSMIC_API_TOKEN"]
headers = {"Authorization": f"Bearer {API_TOKEN}"}

# List all Buckets
resp = requests.get("https://api.cosmicjs.com/v3/buckets", headers=headers)
buckets = resp.json().get("buckets", [])

for bucket in buckets:
    slug = bucket["slug"]
    print(f"\n=== {bucket['title']} ({slug}) ===")

    team_resp = requests.get(
        f"https://api.cosmicjs.com/v3/buckets/{slug}/team",
        headers=headers,
    )
    members = team_resp.json().get("members", [])

    for m in members:
        print(f"  {m['email']:30s} {m['role']:12s} Last login: {m.get('last_login', 'never')}")

SSO and Enterprise Authentication

Cosmic supports enterprise authentication on higher-tier plans:

Google OAuth -- Sign in with Google (available on all plans)
GitHub OAuth -- Sign in with GitHub (available on all plans)
SAML 2.0 -- Available on Enterprise plans for Okta, Azure AD, OneLogin integration
Custom SSO -- Contact Cosmic support for custom OAuth/OIDC providers

Configuring SAML SSO (Enterprise)

Go to Organization Settings > Security
Enable SAML Single Sign-On
Configure:
- Identity Provider SSO URL: https://your-idp.com/sso/saml
- Identity Provider Certificate: Paste the X.509 certificate
- Default Role: Role assigned to new SSO users (e.g., editor)
Test the configuration with a non-admin user
Enable Enforce SSO to require all users to authenticate via SAML

API Key Security

When a user leaves, manage API key access:

# List all API keys for a Bucket
curl -s "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/keys" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN"

# Regenerate read key
curl -X POST "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/keys/regenerate" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "read_key"}'

# Regenerate write key
curl -X POST "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET_SLUG/keys/regenerate" \
  -H "Authorization: Bearer YOUR_BUCKET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "write_key"}'

Offboarding Checklist

Remove the team member from Bucket Settings > Team (or via API)
Regenerate API keys -- Rotate read_key and write_key if the departing user had Developer or Admin access
Review webhooks -- Check for webhooks the user may have configured that point to external services
Audit Object Types -- Verify no schema changes were made that could affect content delivery
Check connected apps -- Remove any OAuth connections the user set up (GitHub, Netlify, etc.)
Update SSO -- If using SAML, deactivate the user in your identity provider
Transfer Bucket ownership if the departing user is the Bucket owner
Review recent API activity -- Check the API usage logs for any unusual patterns before departure

Nach oben