Authentication

All programmatic access to sharedrop requires an API key. This page covers how to create, use, and manage API keys across the API, CLI, and MCP.

API Keys

Creating a Key

1. Go to Dashboard > Settings > API Keys
2. Click Create API Key
3. Give it a descriptive name (e.g., "CI Pipeline", "Claude Agent")
4. Copy the key immediately -- it is only shown once

Key Format

sharedrop uses two types of API keys:

Prefix	Type	Scope
sd_	Personal	Your account. Pages are owned by you.
sdw_	Workspace	A workspace. Pages are owned by the workspace.

Personal keys (sd_) act on your behalf. Workspace keys (sdw_) act on behalf of a workspace and are scoped to that workspace's pages.

Backward compatibility: Legacy API keys with pstr_/pstw_ prefixes continue to work. New keys are generated with sd_/sdw_ prefixes.

Show-Once Policy

API keys are shown only once at creation time. If you lose a key, revoke it and create a new one. Keys are stored as SHA-256 hashes -- sharedrop cannot recover your key.

Using Keys

REST API

Pass your API key as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer sd_your_api_key_here" \
  https://sharedrop.cloud/api/v1/pages

Every API request must include this header. Requests without a valid key receive a 401 UNAUTHORIZED error.

CLI Authentication

The CLI supports three authentication methods, checked in priority order:

1. Environment Variable (Highest Priority)

Set SHAREDROP_TOKEN in your environment:

export SHAREDROP_TOKEN=sd_your_api_key_here
sharedrop list

Best for CI/CD pipelines and automation.

2. Project .env File

Create a .env file in your project directory:

SHAREDROP_TOKEN=sd_your_api_key_here

The CLI reads .env from the current working directory.

3. Stored Credentials (via sharedrop login)

Run sharedrop login to authenticate interactively:

sharedrop login

This opens your browser, authenticates you via sharedrop, and stores a CLI-specific API key in your system config directory (~/.config/sharedrop/).

Auth Priority

When multiple auth sources are available, the CLI uses this priority:

1. SHAREDROP_TOKEN environment variable
2. .env file in current directory
3. Stored credentials from sharedrop login

The first valid token found is used. This means you can override stored credentials with an environment variable for CI.

MCP Authentication

Remote MCP (Recommended)

Pass your API key in the MCP server configuration:

{
  "mcpServers": {
    "sharedrop": {
      "url": "https://sharedrop.cloud/api/mcp",
      "headers": {
        "Authorization": "Bearer sd_your_api_key_here"
      }
    }
  }
}

Local MCP

Set the key as an environment variable for the local MCP server:

{
  "mcpServers": {
    "sharedrop": {
      "command": "npx",
      "args": ["-y", "@sharedrop/mcp"],
      "env": {
        "SHAREDROP_API_KEY": "sd_your_api_key_here"
      }
    }
  }
}

Revoking Keys

To revoke an API key:

1. Go to Dashboard > Settings > API Keys
2. Find the key you want to revoke
3. Click the delete button

Revoked keys are immediately invalidated. Any requests using a revoked key will receive a 401 UNAUTHORIZED error.

Security Best Practices

• Never commit API keys to source control
• Use environment variables or .env files (add .env to .gitignore)
• Create separate keys for different environments (dev, staging, production)
• Use workspace keys for team projects instead of sharing personal keys
• Revoke keys you no longer need
• Rotate keys periodically