Auto-provision an API key

Every Raindrop user can mint API keys to call the public API on their own behalf. The flow below is exactly what the System → API setup page in the Raindrop app does — you can use it programmatically when you need to bootstrap a new integration without clicking through the UI.

1. Get an Auth0 access token

Authorize the user

Run the standard Auth0 PKCE flow against authd.raindrop.com with the audience your integration uses. The returned access_token is the bearer for every subsequent /apikey/* call.

POST https://authd.raindrop.com/oauth/token
{
  "grant_type": "authorization_code",
  "code": "<from /authorize redirect>",
  "code_verifier": "<PKCE verifier>",
  "client_id": "<your Auth0 client_id>",
  "redirect_uri": "<your redirect>"
}

2. Create the key

`POST /apikey/create`

Pass the user the key is on behalf of, a human-readable name, and the Auth0 bearer.

curl -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<user uuid>","name":"ci-deploys"}' \
  https://stgapi.raindrop.com/apikey/create

Save the response immediately. The full api_key is returned only on this call. Subsequent reads only show the last few characters. Lose it and you have to rotate.

3. Use the key

Authorized calls

Send the API key as a bearer token. The API resolves the user, role, and tenant from the key, then applies the same Hasura permissions a logged-in session would.

curl -X POST \
  -H "Authorization: Bearer $RAINDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ user(limit: 5) { id name } }"}' \
  https://stgapi.raindrop.com/gql

4. Rotate or expire

`POST /apikey/replace` / `POST /apikey/expire`

Both endpoints take the same Auth0 bearer plus the key id you want to rotate or expire. /replace returns a fresh api_key (again, one-time visible) and immediately invalidates the old one.

curl -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_id":"<id from /apikey/list>"}' \
  https://stgapi.raindrop.com/apikey/replace

Reference implementation

The Raindrop app's SystemTabApiSetup component drives this exact flow — see raindrop/src/components/System/SystemTabApiSetup.tsx. It uses getAccessTokenSilently for step 1 and posts to the same three endpoints documented here.