Authentication

Every API request must include an Authorization: Bearer <key> header. Keys are created in Settings → API Keys in the Hyperclip app and authenticate as the user who created them — they can spend that user’s credits.

Key format

hck_{env}_{12-char prefix}.{32-char secret}

Part	Length	Purpose
`hck_`	4	Brand identifier. Constant.
`env`	4	`live` (production). `test` is reserved for future sandboxing.
`prefix`	12	Base62. Stored plaintext. Safe to log — used to look up the hashed secret on every request.
`.`	1	Separator.
`secret`	32	Base62. Bcrypt-hashed on the server and never round-tripped back to the client.

Example: hck_live_AbCdEf123456.0123456789abcdefghijklmnopqrstuv

The prefix is shown in the UI so you can identify a key without seeing the full secret. If you leak the prefix in a log, your secret is still safe — revoke the key out of caution, but there’s no immediate compromise.

Sending the key

import { Hyperclip } from "hyperclip";

// reads HYPERCLIP_API_KEY from process.env; base URL defaults to production
const hc = new Hyperclip();

// or pass the key explicitly
const hc2 = new Hyperclip({ apiKey: "hck_live_..." });

from hyperclipco import Hyperclip

# reads HYPERCLIP_API_KEY from os.environ; base URL defaults to production
hc = Hyperclip()

# or pass the key explicitly
hc2 = Hyperclip(api_key="hck_live_...")

curl $HYPERCLIP_BASE_URL/runs \
  -H "Authorization: Bearer hck_live_AbCdEf123456.0123456789abcdefghijklmnopqrstuv"

await fetch(`${BASE}/runs`, {
  headers: { Authorization: `Bearer ${process.env.HYPERCLIP_API_KEY}` },
});

The SDKs handle the header for you on every request. For raw HTTP, prepend Bearer to the key (with the space) and pass it as the Authorization header.

Creating a key

Developers

Open the page from the sidebar or go directly to /developer.

Click New key

Choose a descriptive name. Up to 25 active keys per user.

(Optional) set caps

Monthly credit cap — blocks runs with HTTP 402 when exceeded. Useful for containing cost on an integration key. Per-run credit cap — blocks a single run whose estimated cost is higher than this value. Useful against misconfigured clients that loop.

Copy the secret

You see the full hck_live_... key exactly once in the reveal dialog. Save it to your secret manager immediately.

If you close the reveal dialog without copying, there is no way to recover the secret. Revoke the key and create a new one.

Scopes

Every key carries a list of scopes. Defaults: runs:write, runs:read.

Scope	Allows	Used by
`runs:write`	Create runs, cancel runs	`POST /runs`, `POST /runs/:id/cancel`
`runs:read`	List and poll runs	`GET /runs`, `GET /runs/:id`
`flows:read`	List and fetch saved flows	`GET /flows`, `GET /flows/:id`

A request without the required scope returns 403 insufficient_scope.

Create separate keys per deployment. Production, staging, and each developer’s laptop should each have their own key. One leak then revokes one integration instead of taking down everything.

Revoking a key

Click the trash icon next to a key in Settings → API Keys, confirm, and the key is revoked instantly. In-flight requests authenticated with that key finish; new requests return 401 revoked_api_key. Revocation is a soft delete — the row stays in the database so you can still see the key’s usage history. The secret is destroyed and can no longer authenticate.

Rotating keys

Hyperclip does not auto-rotate keys. For a planned rotation:

Create the replacement key

Mint a new key with the same caps and scopes as the old one.

Deploy the replacement

Roll the new secret out to your environment. Wait until all traffic is on the new key.

Revoke the old key

Revoke in the UI. Done.

Server-side only

Never embed API keys in client-side code. Keys authenticate as you — whoever has the key can spend your credits, trigger runs, and read every flow in your account. Always call the Hyperclip API from a server you control, proxying requests from your frontend.

Acceptable homes for keys:

Backend services, cron jobs, Lambda functions
CI/CD secrets (GitHub Actions, Vercel/Netlify env vars)
Secret managers (AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, 1Password, Doppler)

Unacceptable homes:

.env committed to git
Single-page app JS bundles
Browser extension packages
Mobile app binaries
Shared Slack messages

Rate limits

The API v1 has no per-second rate limiting at the HTTP layer. Abuse is self-limited by:

The credit balance on your account — runs cannot reserve credits beyond your balance.
The monthly cap on the API key — a runaway loop blocks itself after hitting the cap.
Payment declines — a failing autorefill auto-disables itself after one declined charge.

If you need burst capacity, set a generous autorefill threshold or bump the monthly cap on the key.

Security audit checklist

Keys stored only in secret managers, not in source control
Separate key per deployment target
Monthly cap set on every key
Per-run cap set on keys used by user-facing integrations
Autorefill’s topup_credits sized for your worst reasonable hour, not day
API calls proxied through your server, never the browser
Key rotation procedure documented in your runbook

Introduction

Endpoints

Reference

Examples

AI tooling

Key format

Sending the key

Creating a key

Scopes

Revoking a key

Rotating keys

Server-side only

Rate limits

Security audit checklist

​Key format

​Sending the key

​Creating a key

​Scopes

​Revoking a key

​Rotating keys

​Server-side only

​Rate limits

​Security audit checklist

Key format

Sending the key

Creating a key

Scopes

Revoking a key

Rotating keys

Server-side only

Rate limits

Security audit checklist