Connect

Connect links one player of your game to one Discord member of a community on CEEJAY. The player presses a button in your game, authorises the connection with their Discord account on a page CEEJAY serves, and your game receives the member's name, avatar, level, coins and shared roles to show.

This page is for the studio's developers. It explains the flow, step by step, for each of the three ways a connection can start.

What you need

• Connect switched on. It is switched on per instance. Where it is off, every request on this page returns 404 with the code not_available and feature: "players": hide the button.
• A game set up for the community. We set a game up for you for now; dashboard setup is coming soon. A game has a slug (such as rugby_manager), a name and logo for the connect page, an audience, and the settings in the table below.
• A public key for the game. It starts with ceejay_pk_, ships inside the game and is not a secret. A game can have up to 5 at a time, so a new build can carry a new key before the old one is retired.
• For a studio with its own server: a secret key with the players:connect scope. A Full Access key does not include it: see Authentication.

What we save for a game, and what to send us:

What a game stores

Each is accepted by one kind of request only and is recognised by its prefix. A secret key (ceejay_sk_) never goes into a game.

Confirmation from both sides

Nothing is saved until both sides have confirmed, each seeing the other:

• The member's consent. The member presses Connect on CEEJAY's page, having been shown the game, the player's name and the player's ID.
• The game's confirmation. The game shows its player the Discord name and avatar that were authorised, and the player confirms.

A link, a QR image or a code can be seen by someone else: on a stream, on a shared screen, on a console in a living room. Whoever opens it can authorise with their own Discord account. The game's step is where the player sees that it was not them and selects No, before anything is saved. So there is no default: ask the player every time.

Proof levels

Steam. A game on Steam verifies its player with proof: { type: "steam", token }, where the token is the hex ticket of GetAuthTicketForWebApi("ceejay") and the playerId is the player's SteamID64. CEEJAY checks the ticket with the community's publisher Web API key, saved under Connected Apps › Steam, for the app ID saved in the game's proof settings. A valid ticket gives the verified level. CEEJAY accepts each ticket once, so get a new one for every request.

A game can verify who its player is, or supply only an ID.

A basic connection never blocks anyone. A verified connection for the same player replaces it, and a new device or a reinstall connects again through Discord. A game can be set up to connect verified players only.

The level also decides what a device may do with a member's coins. A basic device can read, do quests and check in, but it cannot buy or claim unless the community's team allows a basic connection to spend. The game loop has the table.

The game starts it

This is the usual way in. It needs the public key and nothing on your side but the game.

A session lasts 10 minutes. After that the result is expired, and the button goes back to not connected.

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", "returnTo": "game" }'

Your server starts it

Use this when your game contains no CEEJAY code, or when you want your server to make every request. Your server uses a secret key with players:connect, and never the requests a game makes: those are rate limited per IP address, and a server has one.

If your players signed in to your game with Discord, you already know which member each player is. Skip all of this and call Link an account with the game's slug as platform. Your server creates that link without member approval, so the member sees no page, and the game gets no player session for them until they have completed Connect once.

The member starts it in Discord

A member can also start from the community's server. The community posts the game's button in a channel, and the two sides confirm each other:

Where the community has not posted the button, or a code was used or has expired, no pending request matches it, and code returns 404 with the code code_not_found. The code a game shows its player is a different one: it is typed on CEEJAY's page, never into a game.

Opening the link

The game always polls for the result. Returning to the game only triggers the next poll immediately, so nothing depends on a phone switching back.

The URL to enter a code at is the dashboard URL of the community's instance followed by /connect. qrUrl is an SVG QR code for the link, so a console game needs no QR code of its own.

To bring the player back, send returnTo with the key of one of your return URLs. The connect page then offers "Return to the game", a plain link to that URL with ceejay=return and session (the session's ID) appended. It contains no secret.

What the member sees

The connect page is CEEJAY's, at the dashboard's URL. It shows the community's name and icon and your game's name and logo, in the language you sent as locale.

1. Sign in. The game, the player's name and the player's ID, and "Continue with Discord". When the game sent no proof, the page says the game could not verify who the player is.
2. Discord's own screen, which asks the member to authorise the connection.
3. Review. Who is signed in, with a way to use a different Discord account. The game and the player. What the community's team will see. What the game will receive: which Discord account it is, the nickname, level, XP and coins, and the shared roles. The game's data controller. Then Connect and Cancel.
4. Back to the game. "Go back to the game to finish. It will ask you to confirm" and the Discord name.

Instead of connecting, the page shows a different screen when a connection already exists:

Where the community offers it, a player who is not in the server can tick "Also join". Joining is a separate authorisation on Discord's side.

A member manages their connections at the dashboard's URL followed by /connect/mine, with nothing but their Discord account: what is shared, which devices are signed in, and Disconnect. The game gets that URL as manageUrl.

Staying connected

A player session lasts 15 minutes. The device renews it with Renew a player session, which also replaces the refresh token. A refresh token is valid for 90 days from its last use.

On start-up a game looks, in this order, for:

1. An open session it stored. Keep polling for its result.
2. A refresh token. Renew.
3. A proof token from its sign-in service. Call Get connection status, and start with the proof when the player is connected.

The button in your game has four states:

Three rules keep a device signed in: store the new refresh token before you use the new player session, renew one call at a time, and when a response was lost send the token you still have. Renew a player session explains why.

A second device

A connection supports up to 5 devices. A sixth signs out the least recently used device.

A new device has a hold period before it can spend a member's coins, however it was approved: see The rules about money.

• With proof. When the connection is verified and was made with the member's own consent, a new device that verifies the same player is approved immediately by Start connect: alreadyConnected is true, and no one is asked.
• Without proof. The device goes through Discord again. The page shows "Sign another device in", and the member sees every signed-in device on their connections page.

A player who is not in the server

The connection is saved all the same. The member card says not_member or left, no player session is issued, and joinUrl is where to send the player. The refresh token still works for Disconnect, and a renewal returns a player session once the player has joined.

Age

A game is set up with an audience, and there is no default.

• A game directed at children cannot use Connect: every request returns 403 with the code audience_not_allowed. The two exceptions are Disconnect a player and Delete a player: a studio can always end a connection and delete a player's data.
• A game for a mixed audience sends underAge with every start. Without it the start returns 400 with the code age_answer_required.
• underAge: true returns 403 with the code under_age and stores nothing. When the player is verified, any connection they have is ended.
• underAge: true on a player or an event in Set player fields or Log player events ends the connection in the same way. Because it ends a connection, the key needs players:connect for it.
• A connection that ended this way is not linked again by a key: Link an account returns 403 with the code under_age for that member and game, until the member connects again through Connect.

Disconnecting

A player can always end their own connection:

• In the game, with Disconnect and the refresh token. It works whether or not they are in the server.
• On their connections page, with nothing but their Discord account.
• Through the community's team, who can end it for them.

A member who disconnected themselves is not linked again by a key: Link an account returns 409 with the code member_disconnected until the member connects again. A studio's server ends a connection with Disconnect a player, and deletes the player data CEEJAY stores with Delete a player. Either sends player.disconnected.

From a browser game

The requests a game makes can be sent from a web page.

• The page's origin has to be on the game's list. Any other origin returns 403 with the code origin_not_allowed. A request with no Origin header, which is what a native game sends, passes.
• Send the headers Authorization and Content-Type and no other. The response to the browser's preflight request allows exactly those two.
• No cookie is read, and Access-Control-Allow-Credentials is never sent.

Testing on a live community

A public key can be made in test mode. A session started with a test key accepts consent only from someone who owns the server or has a role with the Administrator permission. Everyone else sees that the page is not available, so a studio can try the whole flow on a live community without touching its members.

Limits

The requests a game makes are counted per IP address, and the Connect requests of a server per game. Rate limits has the numbers.

The two API files

• /openapi.json describes the requests a secret key makes: the five Connect ones, and the eight about players and the field map.
• /openapi-connect.json describes the seven requests of Connect that a game makes, and the eleven requests of the game loop.

After a player is connected

Once connected, the player can earn rewards, sync data and trigger webhook events:

• Rewards. A community can grant a reward for connecting, and for the events a game logs. CEEJAY's bot grants them shortly afterwards, and the result's reward shows the reward status. See Game rewards.
• A role. A community can assign the connection role to connected members. The role is removed when the connection ends.
• Player data. Your server sends a player's fields and events with Set player fields and Log player events, reads a player with Get a player and List players, and settles the field names with the community in the field map. See Player data.
• Webhook events. player.connected and player.disconnected notify your server when a connection is made and when it ends.
• The game loop. A game can show the community's quests, shop, locker, rank and daily reward for the connected player, and sell from its shop with the player's coins. See The game loop.

What follows

These are not in this release. Nothing on this page depends on them.

• SDKs for Unity and Unreal Engine are preview releases, currently in testing. Browser games use the Connect client; other engines use a game kit or the recipe.

Related

• Start connect, Get the result and Confirm connect
• Renew a player session, Get the player's profile and Disconnect
• Create a connect pass and Create a connect session
• Player data, The field map and Game rewards
• The game loop: quests, shop, locker, rank and the daily reward in the game, and the rules for spending
• Errors lists every code of Connect
• The TypeScript SDK has a Connect client for the game and functions for your own server.