Authentication

Every /v1 endpoint requires an API key. Keys are created and managed in the console at /dashboard/keys.

Sending your key

Use either header. Both are equivalent.

Header	Example
X-API-Key (recommended)	X-API-Key: shapi_xxxxxxxx
Authorization	Authorization: Bearer shapi_xxxxxxxx

curl https://api.serphubapi.com/v1/account \
  -H "Authorization: Bearer shapi_xxxxxxxx"

Do not put keys in query strings, front-end code or public repositories. Call SerpHubAPI from your server, or from an agent runtime you control.

Key format

• New keys start with shapi_.
• Older keys starting with fapi_ remain valid and work exactly the same way. You don't need to rotate them.
• A key is shown only once, when it is created. We store a hash, not the key itself. If you lose a key, create a new one and disable the old one.

Managing keys

At /dashboard/keys you can:

• Create several keys with a name, e.g. one per environment or per customer project.
• Disable, re-enable or delete a key. Disabled keys are rejected immediately.
• Set a daily credit limit per key. Once the key has spent that many credits in the current UTC day, further calls with it return 429 rate_limited with the message daily credit limit for this API key reached until the next day. Other keys on the account are unaffected.
• Set an IP allowlist per key (single IPs or CIDR ranges). Requests from any other address are rejected with 401 invalid_api_key. Leave it empty to allow all addresses.

All keys on an account share the same credit balance.

Rate limits

Requests are rate limited per key, per minute. Every successful response includes:

Header	Meaning
X-RateLimit-Limit	Requests allowed per minute for this key
X-RateLimit-Remaining	Requests left in the current window
X-RateLimit-Reset	Seconds until the window resets

When you go over the limit you get 429 with error code rate_limited and a Retry-After header (seconds). Wait that long and retry. If you need a higher limit, write to support@serphubapi.com.

Authentication errors

All authentication failures return 401 with code invalid_api_key. The message tells you why:

Message	Cause
missing or invalid API key	No key sent, or the key does not exist
API key is disabled	The key was disabled in the console
account is suspended	The account is suspended — contact support
request IP is not in this API key's allowlist	The calling IP is not on the key's allowlist

See Errors for the full list.