Authentication
People and agents sign in through the browser:
- CLI: run
sharedrop loginonce. 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
- Go to Dashboard > Settings > API Keys
- Click Create API Key
- Give it a descriptive name (e.g., "CI Pipeline", "Claude Agent")
- 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 withsd_/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/pagesEvery 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 listBest for CI/CD pipelines and automation.
2. Project .env File
Create a .env file in your project directory:
SHAREDROP_TOKEN=sd_your_api_key_hereThe CLI reads .env from the current working directory.
3. Stored Credentials (via sharedrop login)
Run sharedrop login to authenticate interactively:
sharedrop loginThis 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:
SHAREDROP_TOKENenvironment variable.envfile in current directory- 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:
- Go to Dashboard > Settings > API Keys
- Find the key you want to revoke
- 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
.envfiles (add.envto.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
| Scope | What it allows |
|---|---|
pages:read | Read and list pages available to a personal key. |
pages:write | Create folders, upload, update, move, delete and restore pages available to a personal key. |
workspace:pages:read | Read and list pages in the key's workspace. |
workspace:pages:write | Create folders, upload, update, move, delete and restore pages in the key's workspace. |
workspace:members:read | List workspace members and invitations. |
workspace:members:write | Invite, remove and change workspace members. |
system:read | Read administrator statistics via GET /api/v1/admin/stats. |
system:write | No 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.