Start connect

POST /v1/connect/start · for public key

Call it when a player presses Connect in your game. The response includes a link, a code and the URL of a QR image; the player approves with their Discord account on CEEJAY's connect page, and the game learns the result with Get the result. Connect explains the whole flow.

Body parameters

Returns

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/connect/start \
  -H "Authorization: Bearer $CEEJAY_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "playerId": "p_19",
    "playerName": "Nova77",
    "proof": {
      "type": "pass",
      "token": "ceejay_pass_4f8a2c1e9b7d3e41f8a6b0c1d25f0c2a9b7d3e41f8a6b0c1d24f8a2c1e9b7d3e"
    },
    "returnTo": "game"
  }'

The TypeScript tab calls connect.start of the Connect client in the TypeScript SDK. It stores the session secret in its own storage and returns the session without it. For a code the player made in Discord, call connect.startWithCode instead.

{
  "success": true,
  "data": {
    "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN",
    "status": "pending",
    "url": "https://ceejay.communitystudios.xyz/connect/s/kT3v9QmZ1xY7bLw2RfA8cN",
    "qrUrl": "https://ceejay.communitystudios.xyz/connect/s/kT3v9QmZ1xY7bLw2RfA8cN/qr",
    "code": "K7M-2QX",
    "sessionSecret": "ceejay_cs_4f8a2c1e9b7d3e41f8a6b0c1d25f0c2a9b7d3e41f8a6b0c1d24f8a2c1e9b7d3e",
    "expiresAt": "2026-10-08T18:14:11.000Z",
    "pollIntervalSeconds": 3,
    "proof": "verified",
    "alreadyConnected": false,
    "member": null
  }
}

{
  "success": true,
  "data": {
    "sessionId": "kT3v9QmZ1xY7bLw2RfA8cN",
    "status": "needs_game_confirmation",
    "url": null,
    "qrUrl": null,
    "code": null,
    "sessionSecret": "ceejay_cs_4f8a2c1e9b7d3e41f8a6b0c1d25f0c2a9b7d3e41f8a6b0c1d24f8a2c1e9b7d3e",
    "expiresAt": "2026-10-08T18:14:11.000Z",
    "pollIntervalSeconds": 3,
    "proof": "verified",
    "alreadyConnected": false,
    "member": {
      "displayName": "Nova",
      "avatarUrl": "https://cdn.discordapp.com/avatars/409876543210987654/a1b2c3d4e5f60718293a4b5c6d7e8f90.png"
    }
  }
}

What to do with the response

Store sessionId, sessionSecret and expiresAt immediately, in the same place you keep the refresh token. A phone often closes a game while its player is in the browser, and a secret kept only in memory would be lost.

Then open url in a browser, or show code with the URL to enter it at and the image at qrUrl. Never open the link in an embedded web view: Discord refuses to sign in there. Poll for the result every pollIntervalSeconds.

Proof

For firebase and unity the token has to be for the project saved for your game, not expired, and for the playerId you send. A basic connection shows the member in the game on the device that connected. It does not verify who owns the player, so a verified connection for the same player always replaces it. A game can be set up to connect verified players only: a basic start then returns 403 with the code proof_required.

With a code

A member can start in Discord, where they get a code to enter in the game. Send it as code with the player. No new session is created: the player is attached to the member's session, the code is cleared, and member identifies whose code it was. Show that name to the player with the option to confirm or cancel before you send Confirm connect. A player who was tricked into entering someone else's code sees a stranger's name there.

The code comes from the game's button in the community's Discord server: the member presses it and gets a code that works once and lasts 10 minutes, and then enters it in the game. Where the community has not posted the button, or the code has been used or has run out, no open request has it and code returns 404 with the code code_not_found.

A player who is already connected

When the proof is verified and was issued in the last 10 minutes, and this player is already connected at the verified level with the member's own approval, nobody is asked again: status is approved and alreadyConnected is true. Get the result then returns the tokens for this device. In every other case the member is asked, also when the player is already connected: a basic claim never signs a device in without Discord's approval.

Earlier sessions

A start with verified proof ends every earlier open session for the same player. A basic start ends only earlier basic sessions for that player that came from the same IP address.

Age

A game set up for a mixed audience must send underAge with every start. true returns 403 with the code under_age and stores nothing. When the proof sent with it is verified, a connection the player has is ended. The public key alone ends nothing.

Limits

Over one of them the response is 429 with the code too_many_attempts and retryAfter. When more than 200 unknown codes are sent with one public key in 10 minutes, requests with a code for that key are throttled until the window ends: each response is delayed 2 seconds and the limit drops to 2 attempts per IP address instead of 20.

Errors

The checks run in this order: the fields, the age check, the proof, and only then the limits and the code.

Every error body also carries requestId, and a 400 with the code bad_request names the invalid field in field. Match on code, not on the message text, which can change.

The errors every request of a game shares (the key, the state of the game, the origin, 405, 429, 500) are on the Errors page.