CustomThrottlerGuard - Using API v2 with apiKey

[asadriko]

Hi everyone!

I'm trying to use API v2 and I'm running into some issues. I've already reviewed my .env file and the documentation. The API v2 seems to be working, but I can't authenticate using the apiKey generated on the platform.

I'm wondering if there's a required environment variable that I'm missing. Does anyone know which variables are necessary for API v2 to work properly?

Also, do I need to do any specific configuration in the App environment?

If anyone could share a working example or a checklist of what must be set up, that would help a lot!

Thanks! 🙌

Request:

curl --location 'https://api-v2.mydomain.com/v2/me' \
--header 'Authorization: Bearer custom_live_e94dae6ba163e83cdf08263c3b4d7777'

Response:

{
    "status": "error",
    "timestamp": "2025-06-24T16:03:56.756Z",
    "path": "/v2/me",
    "error": {
        "code": "UnauthorizedException",
        "message": "CustomThrottlerGuard - Invalid API Key",
        "details": {
            "message": "CustomThrottlerGuard - Invalid API Key",
            "error": "Unauthorized",
            "statusCode": 401
        }
    }
}

@PeerRich @dosu

[dosubot[bot]]

For API v2 authentication with an apiKey, make sure your environment includes at least these variables: REDIS_URL (required for the API v2 server to run) and api.keyPrefix (used to process and validate API keys). If you're testing the full app flow, especially with the web frontend, set NEXT_PUBLIC_API_V2_URL as well. Redis must be running and accessible at the URL you provide (source).

Your API key should be sent in the Authorization header as Bearer <apiKey>. The backend strips the prefix (default is cal_, but it can be customized via api.keyPrefix), hashes the key, and checks it against the database (source). If the key is missing, expired, revoked, or the prefix is misconfigured, you'll get a 401 with "CustomThrottlerGuard - Invalid API Key".

Checklist:

1. REDIS_URL is set and points to a running Redis instance.
2. api.keyPrefix matches the prefix of your generated API key (e.g., custom_ if your key starts with custom_).
3. The API key is active and not expired or revoked.
4. The key is sent as Authorization: Bearer <apiKey>.
5. If using the web app, NEXT_PUBLIC_API_V2_URL is set.

If all of these are correct and you still get the error, double-check the prefix and that the key exists in the database. Rate limiting is enforced per key, so hitting limits can also trigger errors, but the message would usually indicate rate limiting rather than invalid key (source).

Let me know if you need help checking any of these!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}