Authentication

People and agents sign in through the browser:

  • CLI: run sharedrop login once. See Quickstart.
  • Connector (MCP): your app opens a Sharedrop sign-in window the first time. See Connect your agent.

API keys are for scripts, CI jobs and servers where nobody can sign in. Pass a key as SHAREDROP_TOKEN for the CLI, or as an Authorization: Bearer sd_... header for the API and the connector. Personal keys start with sd_; workspace keys start with sdw_.

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:

PrefixTypeScope
sd_PersonalYour account. Pages are owned by you.
sdw_WorkspaceA 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, so 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 (like gh/glab), authenticates you, and stores a CLI-specific key in your OS config directory: macOS ~/Library/Preferences/sharedrop-nodejs/, Linux ~/.config/sharedrop-nodejs/, Windows %APPDATA%\sharedrop-nodejs\. It then works from any directory with no env var.

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

Apps that support browser sign-in (most do, including the Claude app, ChatGPT, Claude Code, Codex, Cursor and VS Code) need no key: add the connector address and sign in. See Connect your agent for each app's steps.

If your app can't sign in, or it runs headless (CI, a remote box), pass an API key in a headers block instead. ChatGPT and the Claude app don't accept keys.

{
  "mcpServers": {
    "sharedrop": {
      "type": "http",
      "url": "https://sharedrop.cloud/api/mcp",
      "headers": {
        "Authorization": "Bearer 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

API key scopes

ScopeWhat it allows
pages:readRead and list pages available to a personal key.
pages:writeCreate folders, upload, update, move, delete and restore pages available to a personal key.
workspace:pages:readRead and list pages in the key's workspace.
workspace:pages:writeCreate folders, upload, update, move, delete and restore pages in the key's workspace.
workspace:members:readList workspace members and invitations.
workspace:members:writeInvite, remove and change workspace members.
system:readRead administrator statistics via GET /api/v1/admin/stats.
system:writeNo API key endpoints currently use this scope.

New workspace keys accept workspace scopes only. Personal keys can use personal scopes and, for system administrators, system scopes. Workspace member scopes require the workspace owner; system scopes require a system administrator. Workspace page operations also check the current member role. Viewers cannot write. Existing workspace keys retain their personal scopes.

An owner empties every item in the workspace bin. A member empties their own items and all trashed workspace folders. A viewer cannot empty the bin. A workspace key needs pages:write, and its creator's current role decides what it can empty. A workspace key without pages:write cannot empty the bin.