ClanStop API V1 — Documentation

Add ClanStop gaming clans, members, and webhooks to your game, Discord bot, or integration. This page walks you from zero to your first successful API call in 3 minutes.

Quick start

Integration architecture in one picture

                                                          ┌─────────────────┐
  Player           Your game server                       │  ClanStop API   │
    │                    │                                └─────────────────┘
    │  joins clan        │                                         ▲
    │ ─────────────────▶ │  lookup player's token                  │
    │                    │ ─────────────────────────────────────▶  │  X-API-Key: csk_…
    │                    │                                         │  X-API-Token: csu_…
    │                    │  (first time?) POST /game-users         │
    │                    │ ─────────────────────────────────────▶  │
    │                    │  ◀──── { user_id, token }               │
    │                    │  cache, then call POST /clans           │
    │                    │ ─────────────────────────────────────▶  │
    │  ◀── clan created  │  ◀──── { clan_id }                      │

The player's game ID becomes a ClanStop user. The token authenticates every subsequent call for that player. If you serve 10,000 players, that's 10,000 tokens your server holds.

Your first request

Paste this into a terminal (replace YOUR_KEY):

curl -H "X-API-Key: YOUR_KEY" \
     "https://clanstop.com/APIs/V1/games"

You should get back a list of supported games as JSON. If you got an error, see error codes.

Authentication

There are two kinds of credentials. Most calls need just the first.

1. App Key X-API-Key

Identifies your game. Use it on every request. Looks like csk_a3f7…. Sent as a header:

X-API-Key: csk_a3f7b9c4d8e1f3a6c5b2a1d9e8f7c4b3

2. User Token X-API-Token

Identifies a specific player. Required whenever an endpoint acts on someone's behalf — creating a clan, editing it, viewing private profile data. Looks like csu_a3f7…. Sent alongside the app key:

X-API-Key: csk_…
X-API-Token: csu_…

3. Server Key cssrv_

A server key is a third credential, used in place of the app key as X-API-Key for a single community-hosted game server. It belongs to a game (not your studio app), is minted self-service by the person running the server, and carries its own rate limit and quota. Looks like cssrv_a3f7….

This exists for the "many people, same game, different servers" world — modded/community dedicated servers where each host wants to credential their own box without sharing your studio key. A server key can provision players and act on a player's behalf for clan read/create/manage; it cannot edit game metadata, mint other keys, or dissolve clans.

How games get user tokens (the production path)

Your server calls POST /game-users with the player's in-game ID. We return a token. Cache it server-side indexed by the player's game ID. Every future API call for that player reuses the cached token — players never see anything.

// First time a player triggers a clan feature in your game
POST /APIs/V1/game-users
{ "external_user_id": "steamid:76561197960265728" }

// We respond with their ClanStop user_id + a token
{ "data": { "user_id": "846858771", "token": "csu_…", … } }

// Store on your server, keyed by your player id. From now on, when
// that player wants to do anything ClanStop-related, you look up the
// token and use it — without ever asking the player.

This requires the CanIssueGameOnlyAccounts flag on your app. A sandbox app (create one at /account/api-apps) has it on by default for testing; production apps get it flipped by staff.

Linking an existing ClanStop account (the player isn't new)

The auto-provision flow above creates a fresh ClanStop account every time a new external_user_id appears. Players who already have a ClanStop account would end up with two separate profiles. The fix: have the player generate a short link code on their existing account and type it into the game.

// 1. Player goes to https://clanstop.com/gameprofiles (signed in)
//    and clicks "Generate link code". They see something like:
//        ABCD-1234   (expires in 9:58)
// 2. Player types ABCD-1234 (or ABCD1234) into your game's link UI.
// 3. Your server calls /game-users with the code on the same body.

POST /APIs/V1/game-users
{
  "external_user_id": "steamid:76561197960265728",
  "code":             "ABCD1234",
  "display_name":     "PlayerOnSteam"
}

// We respond with the EXISTING user's id (no new account created).
// existing=true and is_game_only=false tell you this was a link, not a provision.
{
  "data": {
    "user_id":      "846858771",
    "existing":     true,
    "is_game_only": false,
    "token":        "csu_…",
    "claim_token":  null
  }
}

Codes are 8 chars from an unambiguous alphabet, single-use, 10-minute TTL. The code field is optional on POST /game-users — if absent, behavior is unchanged (new game-only account is auto-provisioned). If present, the link path runs instead.

Failure modes specific to linking:

The manual token path (indie tools, Discord bots, dev scripts)

For projects where the operator is the player — running a Discord bot for their own clan, a personal dashboard, a modder utility — there's a self-service path: sign in to ClanStop, go to Account → API Tokens, pick your app, pick scopes, copy the token, paste into the tool. Not appropriate for distributing to non-technical players.

Rotating an API key

If a key leaks, rotate it from /account/api-apps → your app → Rotate API key. We mint a fresh csk_… and slot the current key into a 7-day grace window: during that window both keys authenticate. Your integration can swap to the new one without dropping a single call.

While a request comes in on the prior key, the response carries:

X-API-Key-Status: prior; expires_in_seconds=453221; expires_in=5d6h

That's the signal to update your config — after the grace expires, the prior key returns auth_invalid.

Sample code

The same call (GET /games) in different languages. All other endpoints follow the same pattern.

curl -H "X-API-Key: csk_YOUR_KEY" \
     "https://clanstop.com/APIs/V1/games"

const resp = await fetch("https://clanstop.com/APIs/V1/games", {
    headers: { "X-API-Key": "csk_YOUR_KEY" }
});
const data = await resp.json();
console.log(data);

import requests

resp = requests.get(
    "https://clanstop.com/APIs/V1/games",
    headers={"X-API-Key": "csk_YOUR_KEY"}
)
print(resp.json())

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

public class ClanStopExample : MonoBehaviour
{
    IEnumerator Start()
    {
        using (var req = UnityWebRequest.Get("https://clanstop.com/APIs/V1/games"))
        {
            req.SetRequestHeader("X-API-Key", "csk_YOUR_KEY");
            yield return req.SendWebRequest();
            Debug.Log(req.downloadHandler.text);
        }
    }
}

Endpoint reference

Every successful response has this shape:

{
  "status": "success",
  "data": { /* the actual payload */ },
  "meta": { "pagination": { /* … */ } }
}

Every error has this shape:

{
  "status": "error",
  "error": {
    "code": "scope_missing",
    "message": "…human readable…"
  }
}

curl -H "X-API-Key: csk_…" \
     "https://clanstop.com/APIs/V1/clans?q=team&limit=5"

curl -H "X-API-Key: csk_…" \
     "https://clanstop.com/APIs/V1/clans/32777684916580"

curl -H "X-API-Key: csk_…" \
     -H "X-API-Token: csu_…" \
     "https://clanstop.com/APIs/V1/me"

curl -X POST "https://clanstop.com/APIs/V1/clans" \
     -H "X-API-Key: csk_…" \
     -H "X-API-Token: csu_…" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Bob Squad",
       "tag":  "BSQ",
       "short_description": "Just a chill clan.",
       "games":     ["apx"],
       "platforms": ["pc"]
     }'

// player joins (outcome depends on the clan's recruiting setting)
{ "user_id": "846858771" }

// owner adds another player directly (user_id != caller)
{ "user_id": "846858771" }

{ "rank_id": "42" }

{ "new_owner_id": "846858771" }

curl -X POST "https://clanstop.com/APIs/V1/game-users" \
     -H "X-API-Key: csk_…" \
     -H "Content-Type: application/json" \
     -d '{
       "external_user_id": "steamid:76561197960265728",
       "display_name": "BobInGame",
       "scopes": ["me:read", "clan:read", "clan:create"]
     }'

{
  "data": {
    "existing":     false,
    "user_id":      "846858771",
    "is_game_only": true,
    "token":        "csu_…",   // store this
    "claim_token":  "a3f7…"    // show this to player
  }
}

Games (write)

If your app owns a game in our catalog, you can keep its public metadata fresh from your own server — description, store/dev URLs, and a live concurrent-online counter. Ownership is assigned by staff at /superadmin/apis/{id}: only one app owns a given game at a time. Reading any game's metadata stays public (just X-API-Key); writes require the game:manage scope on the user token AND your app must be the owner.

curl -H "X-API-Key: csk_…" \
     "https://clanstop.com/APIs/V1/games/apx"

curl -X PATCH "https://clanstop.com/APIs/V1/games/apx" \
     -H "X-API-Key: csk_…" \
     -H "X-API-Token: csu_…" \
     -H "Content-Type: application/json" \
     -d '{
       "about": "Apex Legends — battle royale by Respawn",
       "store_page_url": "https://store.steampowered.com/app/1172470/",
       "dev_page_url":   "https://respawn.com/"
     }'

curl -X POST "https://clanstop.com/APIs/V1/games/apx/online" \
     -H "X-API-Key: csk_…" \
     -H "X-API-Token: csu_…" \
     -H "Content-Type: application/json" \
     -d '{ "current_online": 138420 }'

// stable_identity = true  → a game-wide id exists (SteamID64, Epic id, …)
external_user_id = "steamid:76561197960265728"      // same on every server
// → provision under (game, id). Clan shows up everywhere. No link step, ever.

// stable_identity = false → only session/slot ids exist
external_user_id = "local:{server_id}:{slot}"           // namespaced to this server
// → provision, and if the player expects a clan, prompt for a link code.
//   Linking is per-server in this case — stable ids are strongly preferred.

curl -X POST "https://clanstop.com/APIs/V1/games/7d2d/servers" \
     -H "X-API-Key: csk_…" \
     -H "X-API-Token: csu_…" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Bob'\''s 24/7", "host_note": "us-east, modded" }'

{
  "data": {
    "server_id":          "5",
    "game_id":            138,
    "name":               "Bob's 24/7",
    "api_key":            "cssrv_…",        // store it — shown only once
    "scopes":             ["game_user:provision", "clan:read", "clan:create", "clan:manage", "server:telemetry"],
    "rate_limit_per_min": 120,
    "daily_quota":        50000
  }
}

curl -X POST "https://clanstop.com/APIs/V1/game-users" \
     -H "X-API-Key: cssrv_…" \
     -H "Content-Type: application/json" \
     -d '{ "external_user_id": "steamid:76561197960265728" }'

curl -X POST "https://clanstop.com/APIs/V1/servers/5/heartbeat" \
     -H "X-API-Key: cssrv_…" \
     -H "Content-Type: application/json" \
     -d '{ "active_user_ids": ["846858771","771203…"], "current_online": 24, "tick_rate": 63.8 }'

curl -H "X-API-Key: csk_…" \
     "https://clanstop.com/APIs/V1/games/7d2d/servers"

curl -H "X-API-Key: csk_…" \
     "https://clanstop.com/APIs/V1/clans/32777684916580/servers"

curl -X DELETE "https://clanstop.com/APIs/V1/games/7d2d/servers/5" \
     -H "X-API-Key: csk_…" \
     -H "X-API-Token: csu_…"

Webhooks

Instead of polling for clan / member / link changes, register a URL and ClanStop will POST signed events to it as they happen. Endpoints are registered staff-side at /superadmin/apis/{id} — pick a URL, pick the events you want, copy the secret once.

Event types

Untick events at registration time to opt out of noise. Untick all (or pass *) to subscribe to everything.

Payload shape

POST <your URL>
Content-Type: application/json
User-Agent: ClanStop-Webhook/1
X-ClanStop-Event: clan.member_joined
X-ClanStop-Event-Id: <32-hex>       // stable across retries — dedupe on this
X-ClanStop-Delivery: <attempt id>
X-ClanStop-Attempt: 1                // 1..6
X-ClanStop-Signature: sha256=<hex>   // HMAC-SHA256 of the raw body

{
  "event":    "clan.member_joined",
  "event_id": "6f3a…",
  "sent_at":  1717059823,
  "app_id":   42,
  "data": {
    "clan_id":  "29401576424788",
    "user_id":  "846858771",
    "actor_id": "846858771",
    "direct":   false      // true when an admin added someone else
  }
}

Verifying the signature

On every delivery we send X-ClanStop-Signature: sha256=<hex> where hex is the HMAC-SHA256 of the raw request body, using the endpoint's secret as the key. Recompute and compare in constant time before trusting the payload — never just ==.

const crypto = require("crypto");

function verify(rawBody, signatureHeader, secret) {
    const expected = "sha256=" + crypto.createHmac("sha256", secret)
                                            .update(rawBody)
                                            .digest("hex");
    const a = Buffer.from(expected, "utf8");
    const b = Buffer.from(signatureHeader, "utf8");
    return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

function verify(string $raw_body, string $signature_header, string $secret): bool {
    $expected = "sha256=" . hash_hmac("sha256", $raw_body, $secret);
    return hash_equals($expected, $signature_header);
}

Rotating the signing secret

If the secret leaks, rotate it on /account/api-apps → your app → webhook row → Rotate. A fresh secret is minted; the old one keeps signing for 7 days. During that window every delivery carries two signature headers:

X-ClanStop-Signature:       sha256=<hex with new secret>
X-ClanStop-Signature-Prior: sha256=<hex with old secret>

Update your verifier to accept either during a rotation. After the grace, only the new header is sent. Pseudocode:

function verify(raw_body, secret_now, secret_prior_or_null) {
    const sig       = header("X-ClanStop-Signature");
    const sig_prior = header("X-ClanStop-Signature-Prior");
    if (verify_one(raw_body, sig, secret_now)) return true;
    if (secret_prior_or_null && sig_prior &&
        verify_one(raw_body, sig_prior, secret_prior_or_null)) return true;
    return false;
}

Retries

Your endpoint must respond 2xx within 10 seconds. Any non-2xx (or no response) triggers a retry. Schedule:

• Attempt 1: immediate (≤1 min)
• Attempt 2: 1 minute later
• Attempt 3: 5 minutes
• Attempt 4: 30 minutes
• Attempt 5: 2 hours
• Attempt 6: 6 hours
• Attempt 7 (final): 24 hours — if this fails, the delivery is dead-lettered and we stop retrying

Dead-letters are visible in /superadmin/apis/{id} → Recent Deliveries panel so staff can spot endpoints that are silently broken. Use X-ClanStop-Event-Id to dedupe — same event id across all retries of the same logical event.

Error codes

Every error response has a stable error.code string. Branch on this, not the human-readable message (which we may polish over time).

Rate limits

Two limits run in parallel:

• Per-minute: 600 requests/minute by default. Going over returns rate_limited.
• Daily quota: 100,000 calls/day by default. Going over returns quota_exceeded until UTC midnight.

Both numbers can be raised per-app — ask staff if your game needs more.

Headers on every response

X-RateLimit-Limit: 600          # your cap
X-RateLimit-Remaining: 487     # left in this window
X-RateLimit-Reset: 1717012345  # unix time when the window resets

Cache and reuse responses when you can. The /games catalog rarely changes — cache it for an hour and you'll save thousands of calls.

FAQ

Wait — do players really have to paste a token into my game?

No, and they shouldn't. That's the manual path, useful for Discord bots and modder utilities, not for commercial games. For a real game the flow is server-side: your game's backend calls POST /game-users the first time a player triggers a clan feature, gets back a token, caches it. The player never sees it, never logs in to clanstop.com unless they want to. See the quick start diagram.

What if my game doesn't have a backend server?

If the game is entirely client-side, the X-API-Key would end up shipped inside the client binary, where it can be extracted by anyone. That's a problem — your key authenticates every call as your game, and an extracted key lets a third party impersonate your game's traffic. Two reasonable options: (1) stand up a thin proxy server that holds the key and brokers calls, or (2) accept the risk and rotate keys when they leak. For anything published commercially, option 1 is the right answer.

Why do I get a different clan_id than what I see in the URL bar?

You shouldn't. Clan IDs are 14-digit strings. If a number looks shorter, you might be parsing them as JavaScript Numbers and losing precision. Treat IDs as strings end-to-end.

My player created a clan but it's not showing in /search?

The public search excludes brand-new clans for a few minutes while indexes catch up. Hitting GET /clans/{id} directly should work immediately.

What's the difference between "game-only" and "real" accounts?

Mechanically — nothing. Both can join clans, post, get banned, etc. The differences:

• A real account has an email + password and can sign in to clanstop.com.
• A game-only account exists only inside your game until the player claims it via /claim-game-account using the claim_token.
• Once claimed, it's a real account. Same UserID. No data lost.

Can I see clans my player created but hasn't joined?

The creator becomes founder automatically — they're always a member of their own clan. GET /me/clans will list it.

How do I test without burning quota?

Read endpoints are cheap and won't blow through your quota during dev. Use them to sanity-check your integration before wiring up writes.

How do community-hosted game servers authenticate?

A server host mints a server key (cssrv_…) for a game via POST /games/{slug}/servers using their own user token. The server then sends that key as X-API-Key. It belongs to the game, carries its own rate limit and quota, and can be revoked without affecting players or clans. See Game servers.

Does a player's clan follow them across different servers?

Yes. Player identity is keyed to the game, not to an individual key, so the game's app key and every server key resolve the same player to the same ClanStop user. A clan shows up automatically on any server its members are active on — the next heartbeat that sees an active member adds the clan to that server's presence list.

What is a stable identity and why does it matter?

If a game exposes a stable, game-wide player id (SteamID64, Epic account id, etc.), servers provision under (game_id, external_user_id) with no link step and the clan appears everywhere automatically. Without a stable id, servers namespace ids per server (local:{server_id}:{slot}) and fall back to one-time link codes — which is why stable ids are strongly preferred.

How do I get my key revoked / quota raised / app approved for game-only accounts?

Email ClanStop staff. We'll respond within a business day.