API authentication fails

SymptomCopy link to Symptom

An API v2 request returns 401 or 403 with missing_credentials, invalid_api_key, key_disabled, api_disabled, legacy_key_unsupported, or a related authentication error.

Most likely causesCopy link to Most likely causes

• Authorization or X-Clan-Id is absent or malformed.
• The secret belongs to a different community.
• The API master switch or individual key is disabled.
• The key was deleted, rotated, copied incompletely, or exposed with extra whitespace.
• A migrated legacy key is being used on /v2.
• The request is going to an old host or version.

Diagnostic checksCopy link to Diagnostic checks

1. Confirm the base URL is https://v3.api.clanlabs.co and the path starts /v2.
2. Check Authorization: Bearer YOUR_API_KEY without logging the real value.
3. Check X-Clan-Id: COMMUNITY_ID against the API settings page.
4. Confirm both the community API switch and key are enabled.
5. Compare the visible key prefix and name, not the secret.
6. Determine whether the key is marked as migrated legacy material.

ResolutionCopy link to Resolution

Correct the two headers or use the key belonging to that Clan ID. Enable the key and master switch if authorised. Rotate a migrated legacy key to create a current cl_live_ secret for /v2, store it once, and update the server-side secret manager.

For Roblox server scripts, keep the key in the experience's secrets store and read it with HttpService:GetSecret(). Never put the key in a LocalScript, experience source code, log, screenshot, or support request.

When to retryCopy link to When to retry

Retry one harmless read after correcting headers or state. Following rotation, the old key stops immediately, or within about a minute if cache invalidation was temporarily unreachable.

Contact supportCopy link to Contact support

Contact Clan Labs support if a newly rotated, enabled key and matching Clan ID fail against the documented API host.

Include this informationCopy link to Include this information

Include method and path, HTTP status, error code and message, Clan ID, key name and visible prefix, rotation time, and a redacted header shape. Never include the secret.