Authentication

Getting a key

Keys are created by a signed-in person, in the dashboard. There is no endpoint that mints a key from an API key, deliberately: a server-side credential that can issue more credentials is a narrow key one request away from a full one, which is the opposite of what scoping is for.

1. Create an account or sign in.
2. Confirm your email address. This is enforced at exactly one place — key creation — and it is the gate on sending, because no key means no mail. An unconfirmed address gets 403 email_unverified.
3. Open Settings → API keys as an owner or admin. A member cannot create or revoke keys.
4. Choose the scopes it needs, and copy the token immediately. The response carries it once and no endpoint will ever show it again.

Using a key

import { Posthaste } from '@posthaste/sdk'

// Read the key from the environment. Never commit one, and never ship one to a
// browser — a key is a server-side credential and carries no user identity.
const posthaste = new Posthaste({ apiKey: process.env.POSTHASTE_KEY })

// Optional, all with sensible defaults:
new Posthaste({
  apiKey: process.env.POSTHASTE_KEY,
  baseUrl: 'https://api.posthastemail.dev', // the default
  timeoutMs: 30_000,                        // per attempt
  maxRetries: 2,                            // 429 and 5xx, with backoff
  fetch: myProxyAwareFetch,                 // anything fetch-shaped
})

The TypeScript SDK sets the header for you and refuses to let a custom header replace it. In any other language, set it yourself — it is one header.

The scheme name is matched case-insensitively and surrounding whitespace is tolerated, so bearer works as well as Bearer. Anything else — a bare token, a query parameter, basic auth — is rejected.

The key id is the first twelve characters after the prefix and is stored in clear, so authentication is one indexed lookup rather than a scan. It is also what the request rate limiter counts against, which is why an unparseable key falls back to being limited by IP.

Live and test keys

A key carries an environment in its prefix: ph_live_ or ph_test_. The prefix must match the key that was created — presenting a live key’s secret under a ph_test_ prefix fails authentication even though the secret is correct.

Scopes

A key grants only what it lists. A missing scope is denied, so an endpoint added later is closed to your existing keys rather than silently reachable by all of them. These nine are the complete set that can be granted:

Asking for a scope outside this list returns 400 invalid_request naming the unknown value, rather than storing a string that would silently satisfy some future check.

Listing your keys

The hundred most recently created keys, newest first, including revoked ones — “what did this key do” has to stay answerable after it stops working, which is exactly when somebody asks. No secret is returned, and none is possible: only an HMAC of it was ever stored.

curl https://api.posthastemail.dev/v1/api-keys \
  -H "authorization: Bearer $POSTHASTE_KEY"

# 200
# {
#   "data": [
#     {
#       "id": "key_Bh4Rm8Ub2Xc6Ye0Zf1Ag3B",
#       "name": "production sender",
#       "environment": "live",
#       "scopes": ["emails:send", "messages:read"],
#       "hint": "ph_live_8Fk2…",
#       "createdAt": "2026-08-01T09:12:44.108Z",
#       "lastUsedAt": "2026-08-18T06:40:11.902Z",
#       "revokedAt": null
#     }
#   ]
# }

Creating and revoking keys (POST /v1/api-keys, DELETE /v1/api-keys/:id) require a dashboard session and refuse bearer keys with 403 forbidden.

When authentication fails