Authentication

Learn how to authenticate your requests to the Cosmic API.

Get your API keys

Cosmic uses API keys to authenticate requests. For the following examples, you will need your:

1. Bucket slug
2. Bucket read key
3. Bucket write key

You can get your API access keys by going to Bucket Settings > API Access in the Cosmic dashboard.

Use your API keys

Use the methods below to use your Cosmic API keys.

// Import
import { createBucketClient } from '@cosmicjs/sdk';

// Authenticate
const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY',
});

// Fetch content
await cosmic.objects
  .find({
    type: 'posts',
  })
  .limit(1);

// Write content
await cosmic.objects.insertOne({
  title: 'Blog Post Title',
  type: 'posts',
  metadata: {
    content: 'Here is the blog post content...',
    seo_description: 'This is the blog post SEO description.',
    featured_post: true,
  },
});

Personal Access Tokens

For dashboard-level API access (managing agents, workflows, account settings, etc.), use a Personal Access Token (PAT) instead of a session JWT. PATs are ideal for scripts, CI/CD pipelines, CLI tools, and MCP servers.

Create a token at Account Settings > API Tokens. Tokens use the cos_ prefix and carry your full account permissions. Learn more in the API Tokens documentation.

Include your token in the Authorization header:

curl https://dapi.cosmicjs.com/v3/users/get \
  -H "Authorization: Bearer cos_YOUR_TOKEN"

PATs are the recommended authentication method for the Agent Messaging API. For example, to send a message to a Communication agent:

curl -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/messages \
  -H "Authorization: Bearer cos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'