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 currently runs two separate auth systems

FaucetPay's API documentation describes a legacy v1 API at the /api/v1 base URL, authenticated by including an api_key field in the POST body alongside your other parameters, and a newer v2 scoped-key API at /api/v2, authenticated by sending the key as an Authorization: Bearer header instead. The two are not interchangeable. A v2 scoped key placed in the v1 api_key field will not authenticate, and a v1 faucet key sent as a Bearer token to a v2 endpoint will not authenticate either, and both failures surface as the same 403.

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 these — for example, 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 current documentation only shows 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 current 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

FaucetPay's documentation states that key 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 the current key lives in the dashboard

For the legacy system, the api_key is revealed from the Faucet Owner Dashboard under the specific faucet's management page. For the scoped v2 system, keys are minted separately from a dedicated Scoped API keys section, shown once at creation and stored hashed afterward, meaning there is no way to view an existing scoped key again — only regenerate a new one if it was lost. Confirm which of these two places you last generated the key from, since they are not the same key.

Rate limiting is a separate failure from a 403

FaucetPay documents a rate limit on the legacy API of roughly 60 requests per minute per faucet key, with short bursts up to 120 tolerated briefly. Hitting that limit is expected to surface differently from an invalid-key error rather than as a 403, so if your integration is making frequent requests, check whether the response you're actually seeing is a rate-limit response before concluding the key itself is invalid.

Build a Request Snapshot before contacting support

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

• The exact base URL called (v1 or v2, full path).
• Whether the key was sent as a body field (api_key) or an Authorization: Bearer header.
• The HTTP method used and the Content-Type header sent.
• Which faucet the key belongs to, if you manage more than one.
• Whether the key was recently rotated or newly minted, and from which dashboard section.
• For a v2 key, which scopes were selected when it was created.
• The exact response body received, including the status field and message.

Worked example — v1 key sent as a Bearer header

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 on the dashboard, 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 — 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. Confirm which base URL the failing request actually hits — v1 or v2.
• 2. Confirm the key is placed where that version expects it: api_key in the v1 body, or Authorization: Bearer for v2.
• 3. Re-copy the key directly from the correct faucet's dashboard section and paste it into plain text to check for hidden characters.
• 4. If it's a v2 key, confirm the scope the failing endpoint needs and check the key was minted with that scope.
• 5. Check whether the key has an IP whitelist set and whether the request is coming from a listed IP.
• 6. Check whether the key was rotated recently and whether every deployment using it was updated.
• 7. If every check above passes and the 403 persists, open one support ticket with the Request Snapshot rather than repeating the same 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 — insufficient balance, an invalid destination, or a currency mismatch — with its own distinct status codes in FaucetPay's reference, 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 checked on August 15, 2026

FaucetPay's current official API reference was the primary source for endpoint behavior, status codes, and the v1/v2 authentication split. Forum reports of the same error were used only to identify which outdated request patterns are still being followed, not as evidence of current API behavior.

• FaucetPay — API reference (v1, v2, status codes, rate limits, security) — https://faucetpay.io/api-docs
• FaucetPay — Help desk — https://faucetpay.io/help
• Kodular Community — forum report of the same 403 invalid-key error, used only as an example of the unresolved user confusion — https://community.kodular.io/t/faucet-pay-api-call-from-local/215575

FAQ