Authentication

Archievery API keys are clan-scoped. A key identifies a clan, not a user.

Where keys live

Keys are created and revoked in the clan settings panel — open a clan on the dashboard and click the settings gear. They are not managed from this site, and they are not in account settings, because a key belongs to a clan rather than to the person who happened to create it.

TODO: the key creation UI is not built yet. This section describes the intended model, not a shipped feature.

Scoping

One key grants access to exactly one clan. There is no account-wide key and no key that spans clans — running three clans means three keys.

This matters for the path: every endpoint carries {clanId} even though the key already implies it. That is deliberate. It matches the existing route structure, it makes a mismatched key a loud 403 instead of a silent write to the wrong clan, and it keeps a request readable in a log.

TODO: What Roblox identity does a key act as? This is the largest open question and it blocks the permission model. Permissions in Archievery come from a member's rank, so a key has to resolve to something before any endpoint can authorize it. Options under discussion:

• The key acts as the clan owner
• The key carries an explicit permission bitmask of its own
• The key is bound to a specific Roblox account at creation time

Sending a key

TODO: the header name is undecided. The existing session-auth middleware reads an api-key header; Authorization: Bearer is the more conventional choice for a public API. Examples on this site currently show Authorization.

curl -X POST \
  "https://API_BASE_URL/v0/clans/CLAN_ID/members/ROBLOX_ID/xp" \
  -H "Authorization: Bearer YOUR_CLAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150, "reason": "Round win"}'

TODO: key format undecided — length, prefix, and whether the clan ID is encoded into the key itself.

Keeping a key secret

Server scripts only. HttpService is unavailable to LocalScripts, but the real risk is not the API call — it is storing the key anywhere a client can read it. Never put a key in a StringValue, a ModuleScript under ReplicatedStorage, or anything else that replicates.

Roblox has no secret store that survives a place file being opened, so treat any key shipped in a place as compromised the moment someone gets the file.

Rotation and revocation

TODO: rotation semantics undecided. Open questions: whether an old key keeps working during an overlap window, whether revocation is immediate or eventually consistent across edge nodes, and how many keys a clan may hold at once.

Manage your keys

Keys are managed on the dashboard, in your clan's settings panel.