FaucetPay API Invalid API Key 403? Check Which Auth Layer Is Actually Failing

A FaucetPay API invalid API key 403 with the message "Invalid API Key used" almost never means the key is literally wrong, especially if you just generated or regenerated it. It far more often means the request reached FaucetPay's server but failed authentication for a reason unrelated to the key's characters being correct: the request was built for the wrong API version, the key was copied with hidden whitespace, a v2 scoped key is missing the scope the endpoint needs, or an IP whitelist on the key is blocking the request. Confirm which of these is actually happening before regenerating the key again, since regenerating a key that was never the problem just resets you back to the same error.

A fresh key returning the same 403 is the important clue

If you regenerated the API key, confirmed it in the dashboard, and the very next request still returns the same "Invalid API Key used" 403, that is a strong sign the problem is not the key's value at all. A wrong or expired key and a correctly-copied key sent the wrong way produce the identical error message, because FaucetPay's server sees an unauthenticated request either way. Rule out how the request is built before touching the key again.

FaucetPay runs two separate auth systems

FaucetPay's API reference, re-checked on October 31, 2026, describes a legacy v1 API at https://faucetpay.io/api/v1, where you pass the faucet's api_key in the api_key field of every POST body, and a newer scoped-key API at https://faucetpay.io/api/v2, where the key goes in an Authorization: Bearer header. The two aren't interchangeable. A v2 scoped key in the v1 api_key field won't authenticate, and neither will a v1 faucet key sent as a Bearer token to v2. The v1 reference describes its 403 as "invalid or missing api_key", which is why both mistakes look identical. The v2 reference lists 401 Unauthorized and 403 Forbidden as separate errors, so on v2 note which of the two you actually got.

Identify which base URL your request is actually hitting

Check the literal URL your code sends the request to. If it starts with faucetpay.io/api/v1, you're on the legacy system and the key belongs in the POST body as api_key. If it starts with faucetpay.io/api/v2, you're on the scoped system and the key belongs in an Authorization: Bearer header, not in the body. Mixing them up, for example by copying a v1-style request and only swapping the endpoint path to v2, is one of the most common causes of a 403 that looks like a bad key but isn't.

Older tutorials and forum threads predate v2

Several third-party integration guides and forum posts describing this exact 403 were written when only the legacy v1 system existed. Some of them build the request as a GET request with api_key placed directly in the URL's query string rather than a POST body. FaucetPay's documentation, checked on October 31, 2026, shows only form-encoded POST requests for both API versions. If your integration follows an older pattern, rebuilding the call as a proper POST with the key in the location the docs specify is worth trying before assuming the key is at fault.

Confirm the request method and content type

FaucetPay's status code reference lists 405 for using the wrong HTTP method and 415 for an unsupported content type, both distinct from 403. If your request is returning one of those instead, that is a different and more specific problem than an invalid key, and fixing the method or header is the actual fix rather than regenerating a key that was never rejected for being wrong.

A copy-paste error is still the simplest explanation

Before looking at anything structural, reopen the dashboard and copy the key again, checking specifically for a trailing space, a line break carried over from a text editor, or a truncated string if the key display area was scrolled. Paste it into a plain text field first to visually confirm its exact length and characters match what the dashboard shows, rather than pasting directly into code where invisible characters are easy to miss.

Using the wrong faucet's key

If you manage more than one faucet on the same FaucetPay account, each faucet has its own separate api_key. A key that is completely valid for one faucet will return the same invalid-key 403 if used against an endpoint intended for a different faucet's balance or payouts. Reopen the specific faucet's Manage page and re-copy the key from that faucet rather than reusing one saved from another project.

Key rotation takes effect immediately, not on next use

For legacy api_keys, FaucetPay's documentation says rotation is immediate: the old key stops working the moment a rotation is confirmed, not the next time it happens to be used. If you or a teammate rotated the key from the dashboard for security reasons and any part of your deployment (a cached environment variable, a secrets manager entry, a second server) still holds the old value, that instance will start returning 403 immediately, even though nothing about your code changed.

A v2 scoped key without the right scope

The scoped v2 API assigns each key one or more specific scopes (read, send, manage or admin) chosen when the key is created. A key minted with only the read scope will fail against an endpoint that requires send, such as issuing a payout, and a key without manage will fail against faucet settings endpoints. This failure is scope-related, not a bad key, and the fix is minting a new scoped key with the correct scope rather than reusing the existing one.

An IP whitelist on the key can block a legitimate request

FaucetPay's scoped-key system supports an optional per-key IP whitelist. If one was set when the key was created, requests from any other IP address will be rejected even though the key itself is valid and correctly formatted. This is easy to overlook after moving code to a new server, a different hosting region, or a local development machine with a different outbound IP than what the key was originally restricted to.

Legacy v1 keys still work, but only on v1 endpoints

FaucetPay's documentation confirms that existing v1 faucet api_key values continue to work on v1 endpoints even after the v2 system launched. If you were told to "upgrade" to v2 and only partially migrated, updating some calls to the new base URL while leaving the old api_key field in the body instead of a Bearer header, that half-migrated request is what produces the 403, not an actual problem with either key.

Where each key lives in the dashboard

The legacy api_key is shown in the Faucet Owner Dashboard on that faucet's management page. Scoped v2 keys are minted separately in a Scoped API keys section. Each one is shown once and then stored hashed, so you can't view an existing scoped key again; if it's lost, you mint a new one. Check which of the two places you last generated a key from, because they aren't the same key.

Rate limiting is a separate failure from a 403

FaucetPay allows about 60 requests per minute per key, with bursts up to 120 tolerated for up to 2 seconds. Going over doesn't produce a 403. On v1 the reference lists 420 "Rate limited", and on v2 it's 429 Too many requests. Send keys on v2 can also carry a daily payout cap in US dollars, set when the key is minted, and exceeding it returns a 429 with no payout made. If your integration is busy, read the status code you're actually getting before deciding the key was rejected.

Capture one failing request before contacting support

Capture these details from one failing request rather than describing the problem from memory.

• The exact base URL and path, v1 or v2
• Whether the key went in the body (api_key) or an Authorization: Bearer header
• The HTTP method and Content-Type header
• Which faucet the key belongs to, if you run more than one
• Whether the key was recently rotated or newly minted, and where
• For a v2 key, the scopes chosen when it was created
• The exact response body, including the status field and message

Worked example: a v1 request pointed at v2

A developer copies a working v1 curl example from an old tutorial, then updates only the URL to point at a v2 endpoint while leaving the api_key in the POST body unchanged. The v2 endpoint expects Authorization: Bearer, not a body field, so the key is never read at all. The fix is either reverting to the v1 base URL with the same key, or minting a proper scoped v2 key and sending it as a Bearer header.

Worked example: key rotated, old value still deployed

A faucet owner rotates their v1 key after a suspected leak, confirms the rotation, and updates the key locally in their development environment. Production, deployed separately, still has the old key baked into its environment configuration. Every production request returns the invalid-key 403 immediately, not gradually, because rotation took effect the moment it was confirmed. Updating the production secret resolves it without needing to rotate again.

Worked example: a read-scope key used for a payout

A script built to only check faucet balances is later extended to also send payouts, reusing the same scoped v2 key that was minted with only the read scope. Balance checks keep working; the new send call returns an authentication error. The balance calls succeeding is the tell that the key format is fine. The problem is scope, and the fix is minting a separate key with the send scope rather than debugging the existing one further.

The practical diagnostic sequence

Work through this before regenerating the key again.

• 1. Check which base URL the failing request hits: v1 or v2.
• 2. Check the key sits where that version expects it: api_key in the v1 POST body, or an Authorization: Bearer header on v2.
• 3. Copy the key again from the right faucet's dashboard section and paste it into plain text to spot hidden characters.
• 4. For a v2 key, check which scope the endpoint needs and whether the key was minted with it.
• 5. Check whether the key has an IP whitelist and whether the request comes from a listed IP.
• 6. Check whether the key was rotated recently and every deployment was updated.
• 7. If all of that passes and the 403 persists, open one support ticket with the captured request instead of repeating the call.

If the real problem is a payout that failed for a different reason

A 403 invalid-key error is an authentication failure before FaucetPay even evaluates the payout itself. If your request authenticates successfully but the payout still doesn't go through, that's a different class of problem, such as insufficient balance, an invalid destination, a currency mismatch or a v2 send key that has hit its daily payout cap. Those have their own status codes in FaucetPay's reference and are not something this page's diagnosis applies to.

If the real problem is a webhook, not an API call you're sending

The 403 covered here applies to requests your code sends to FaucetPay's API. If instead you're failing to verify an incoming webhook delivery from FaucetPay, that involves checking an HMAC signature header against a separate webhook secret, which is unrelated to the api_key or scoped-key authentication described on this page.

Sources

FaucetPay's API reference was the main source for endpoints, status codes and the v1/v2 split, re-checked on October 31, 2026. A forum thread was used only to show which outdated request patterns people still follow.

• FaucetPay API reference (v1, v2, status codes, rate limits, security): https://beta.faucetpay.io/api-docs
• FaucetPay help desk: https://faucetpay.io/help
• Kodular Community thread on the same 403 error, as an example of the confusion: https://community.kodular.io/t/faucet-pay-api-call-from-local/215575

FAQ