API keys

One key per job, each with its own guard rails. Give the scraper in staging a 5,000-credit monthly cap, let the pricing bot call only the three endpoints it needs, and set the contractor's key to expire on Friday. A key that steps out of bounds gets a clear error and is never charged.

Create a key

Open Keys and choose new key. Name it after where it runs (prod-worker, ci, laptop) so the logs make sense later. Add a note if you like.

The full key (it starts with ash_) is shown once. Copy it into your server's environment or secret manager; we keep only a hash and can't show it again.

export APISH_KEY="ash_…"
curl "https://api.api.sh/reddit/v1/subreddit?subreddit=python" -H "x-api-key: $APISH_KEY"

Owners, admins and developers can create keys. Developers manage their own; owners and admins manage everyone's. Every key in a team spends the team's shared balance.

Controls per key

controloptionswhen it's hit
ExpiryNever, 30 days, 90 days, 1 year, or a date you pick.401 "this API key has expired". The Keys page flags keys that expire within 7 days.
Monthly credit capAny whole number of credits, or no cap.402 "this key's monthly credit cap is reached", until the 1st of next month (UTC).
Allowed endpointsAll endpoints, or only the platforms and single endpoints you pick.403 "this API key isn't allowed to call …", with the key's list in allowed_routes.
  • Platforms vs endpoints. Allowing a platform allows all of its endpoints, including most added later. Allowing a single endpoint allows exactly that route.
  • Caps vs spend limits. A key's cap limits that key only. To cap the whole team, use spend limits.
  • Changes apply in about a minute. Edits, revocations and expiry take effect on calls within about 60 seconds, usually sooner.

Refused calls cost nothing. The full list of statuses is in Errors.

Usage by key and member

The Keys page shows each key's credits this month (with a bar against its cap), last use and calls over 30 days. On the Overview, the by key and by member tables break credits down for the period you pick; click a row to filter. Logs filter by key too, and the Account API takes key=<key id> on /v1/logs.

Rotating keys

Keys don't need to change on a schedule, but rotate when someone with access leaves, when a key may have leaked, or as your policy requires. No downtime:

  1. Create a new key with the same controls.
  2. Deploy it everywhere the old one runs.
  3. Watch the old key's last used go quiet on the Keys page.
  4. Revoke the old key. It stops working within about a minute.

Think a key leaked? Revoke it first and rotate after: a revoked key is refused with 401, which is free.

Good habits

  • Keep keys on the server. Never ship one in a browser page, a mobile app or a public repo.
  • One key per service or environment, so you can cut one off without touching the rest.
  • Give experiments a cap and an expiry date. They tend to outlive their welcome.
  • When someone leaves the team, their keys keep working and are marked left: review them.
  • Enterprise teams can also limit keys to their own networks.

Keys you don't create here

Connecting an AI assistant through the MCP server creates a key for that app, shown on the Keys page with an mcp app label. Revoke it like any other key to disconnect the app.