API Keys

Every request to /v1/* requires a Bearer token:

Authorization: Bearer tupk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Getting a key

Tupshar is in research preview. Keys are created through the dashboard:

1. Sign in at https://ui.tupshar.housecarl.cloud.
2. Open the dashboard.
3. Click Create key, give it a label and choose scopes (read or write; write implies read).
4. Copy the tupk_… value immediately — it is shown once and cannot be retrieved again.

Keys expire after 180 days. There is no auto-rotation; create a new key before the old one expires if you need continuity.

What you get by default

Email paul@upside-down-research.com if you need higher limits for your use case.

Using the key

Set it as an environment variable and pass it in the Authorization header:

export TUPSHAR_HOST="https://api.tupshar.housecarl.cloud"
export TUPSHAR_KEY="tupk_…"

curl -sS "$TUPSHAR_HOST/v1/file/01JZ8K3M9QF2YV7X4B6N0CWE5T" \
  -H "Authorization: Bearer $TUPSHAR_KEY"

Keep your key out of source control. Treat it like a password.

Creating keys programmatically (operators)

Operators can mint keys with the tupsharctl CLI or by calling POST /httpserver/keys authenticated with a Clerk browser session (not a tupk_ key):

curl -sS -X POST "$TUPSHAR_HOST/httpserver/keys" \
  -H "Authorization: Bearer <clerk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "my-app", "scopes": "read,write"}'

201 Created:

{
  "id": "key_01JZ…",
  "prefix": "tupk_abc123",
  "cleartext": "tupk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "label": "my-app",
  "scopes": ["read", "write"],
  "created_at": "2026-06-12T21:00:00Z"
}

The cleartext field is the tupk_… value — it is returned once and not stored.

Troubleshooting

401 Unauthorized — key is missing, misspelled, or revoked. Verify the Authorization: Bearer tupk_… header has no extra spaces and the key is correct.

429 Too Many Requests — you've exceeded 60 requests/minute. Wait and retry with exponential backoff.

See also

• HTTP API — all endpoints that require a key
• Quickstart — make your first request