Authenticate API v2 requests

Every public API v2 endpoint requires two headers:

http

Authorization: Bearer YOUR_API_KEY
X-Clan-Id: COMMUNITY_ID

YOUR_API_KEY is the one-time cl_live_… secret. COMMUNITY_ID is the Clan ID shown separately on the API settings page. A key is bound to one community; pairing it with another Clan ID does not grant cross-community access.

Request requirements

For authentication to pass, all of these must be true:

The URL uses https://v3.api.clanlabs.co/v2/....
Both headers are present and correctly formatted.
The API master switch is enabled for the community.
The individual key exists and is enabled.
The key has the endpoint’s required scope.
The community has an active subscription with API access and the endpoint’s feature.

Authorization checks do not replace route validation. A fully authenticated request can still receive 400, 404, 409, or 429.

Authentication failures

Status and code	Meaning	Next action
`401 missing_credentials`	A key or `X-Clan-Id` is absent.	Add both headers.
`401` authentication error	The key shape, secret, or community could not be authenticated.	Check the API host, secret-manager value, Clan ID, and visible key prefix.
`403 api_disabled`	The community API master switch is off.	Enable it in API settings.
`403 key_disabled`	This key is disabled.	Enable it or use a current key.
`403 legacy_key_unsupported`	A migrated legacy key was sent to `/v2`.	Rotate it in Settings → API Keys to issue a `cl_live_` key.
`403 insufficient_scope`	The key lacks the operation’s permission.	Add only the required scope; read `WWW-Authenticate` for its name.
`403 entitlement_required`	The subscription is not active.	Restore the community subscription.
`403 api_access_unavailable`	The plan does not include any API access.	Compare the available plans.
`403 feature_unavailable`	The endpoint’s product feature is unavailable.	Check tier, trial, and feature details.

Server-side storage

Put the secret in an encrypted deployment secret or environment variable.
Use a separate key for each integration and environment.
Never put it in source control, logs, URLs, support messages, frontend bundles, a Roblox LocalScript, or experience source code.
For Roblox server scripts, save it in the Creator Hub secrets store and read it with HttpService:GetSecret().
Redact the Authorization header in monitoring and exception tools.
Rotate immediately after suspected disclosure.

Example request

curl --request GET \
  --url 'https://v3.api.clanlabs.co/v2/members?limit=1' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-Clan-Id: COMMUNITY_ID'

Next, choose the smallest permissions in API keys and scopes.

Every public API v2 endpoint requires two headers:

http

Authorization: Bearer YOUR_API_KEY
X-Clan-Id: COMMUNITY_ID

Request requirements

For authentication to pass, all of these must be true:

The URL uses https://v3.api.clanlabs.co/v2/....
Both headers are present and correctly formatted.
The API master switch is enabled for the community.
The individual key exists and is enabled.
The key has the endpoint’s required scope.
The community has an active subscription with API access and the endpoint’s feature.

Authorization checks do not replace route validation. A fully authenticated request can still receive 400, 404, 409, or 429.

Authentication failures

Status and code	Meaning	Next action
`401 missing_credentials`	A key or `X-Clan-Id` is absent.	Add both headers.
`401` authentication error	The key shape, secret, or community could not be authenticated.	Check the API host, secret-manager value, Clan ID, and visible key prefix.
`403 api_disabled`	The community API master switch is off.	Enable it in API settings.
`403 key_disabled`	This key is disabled.	Enable it or use a current key.
`403 legacy_key_unsupported`	A migrated legacy key was sent to `/v2`.	Rotate it in Settings → API Keys to issue a `cl_live_` key.
`403 insufficient_scope`	The key lacks the operation’s permission.	Add only the required scope; read `WWW-Authenticate` for its name.
`403 entitlement_required`	The subscription is not active.	Restore the community subscription.
`403 api_access_unavailable`	The plan does not include any API access.	Compare the available plans.
`403 feature_unavailable`	The endpoint’s product feature is unavailable.	Check tier, trial, and feature details.

Server-side storage

Put the secret in an encrypted deployment secret or environment variable.
Use a separate key for each integration and environment.
Never put it in source control, logs, URLs, support messages, frontend bundles, a Roblox LocalScript, or experience source code.
For Roblox server scripts, save it in the Creator Hub secrets store and read it with HttpService:GetSecret().
Redact the Authorization header in monitoring and exception tools.
Rotate immediately after suspected disclosure.

Example request

curl --request GET \
  --url 'https://v3.api.clanlabs.co/v2/members?limit=1' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-Clan-Id: COMMUNITY_ID'

Next, choose the smallest permissions in API keys and scopes.

Request requirementsCopy link to Request requirements

Authentication failuresCopy link to Authentication failures

Server-side storageCopy link to Server-side storage

Example requestCopy link to Example request

Request requirementsCopy link to Request requirements

Authentication failuresCopy link to Authentication failures

Server-side storageCopy link to Server-side storage

Example requestCopy link to Example request

Request requirements

Authentication failures

Server-side storage

Example request

Request requirements

Authentication failures

Server-side storage

Example request