Get started

Authentication

API keys, what each one can do, and OAuth for AI apps.

There are two ways to authenticate, and both give the same access to the same library.

  • API keys for your own code, scripts, the CLI, SFTP and agents running unattended.
  • OAuth for AI apps such as ChatGPT and Claude, which sign in once through the MCP server. There's no key to copy.

API keys

Create keys on the API page in the app. Send a key in the Authorization header of every request:

$ curl https://drop.media/api/v1/me -H "Authorization: Bearer YOUR_API_KEY"

A key is shown once, when it's created. Give each script, machine or agent its own key so you can revoke one without breaking the others. Keys belong to the account, so everyone who manages a shared account sees the same keys, along with who made each one and when it was last used.

Abilities

Each key only does what it was given. Ask for the least it needs: a CI job that posts screenshots only needs files:write.

files:readability List, search and get files, and make share links.
files:writeability Upload files and make one-time upload URLs. Also the password for SFTP.
files:deleteability Delete files.

A call that needs an ability the key doesn't have gets 403. GET /me lists the key's abilities.

OAuth for AI apps

The MCP server at https://drop.media/mcp supports OAuth 2.1, so apps like ChatGPT and Claude connect with a sign-in screen instead of a key. They find everything they need on their own:

  • A 401 from /mcp points them at /.well-known/oauth-protected-resource/mcp.
  • They register themselves (dynamic client registration) and send you to drop.media to approve access, using PKCE.
  • They get a token that lasts an hour and a refresh token that lasts 90 days and changes every time it's used.

Connected apps are listed on the Agents page, where you can disconnect them. See AI agents for setup.

Plans and access

API keys, the CLI, MCP and SFTP work on every plan. On the free plan the account's email address must be verified first. Until then, calls return 402 with a message saying what to do.

Keeping keys safe

  • Keep keys out of source control. The CLI reads DROP_API_KEY, and so can your own code.
  • Revoke a key the moment it might have leaked. Anything using it stops working straight away.
  • Every call a key makes is in Logs for 30 days, with its IP address and client.