Get connection status

Check whether a player is connected, from a game that can verify who the player is.

POST /v1/connect/status · for public key

Use it on a new device or after a reinstall, when the game has no refresh token stored and its player has signed in with Firebase or Unity. The response is connected and nothing else: no member data is returned.

Body parameters

Prop

Type

Returns

Prop

Type

Example

Request

curl -X POST https://ceejay.communitystudios.xyz/api/v1/connect/status \
  -H "Authorization: Bearer $CEEJAY_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "playerId": "p_19",
    "proof": {
      "type": "firebase",
      "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.eyJzdWIiOiJwXzE5In0.c2lnbmF0dXJl"
    }
  }'

The TypeScript tab calls connect.getStatus of the Connect client in the TypeScript SDK. It returns connected, and nothing else.

200 OK

{
  "success": true,
  "data": {
    "connected": true
  }
}

Who can ask

The proof must be verified and issued in the last 10 minutes. So with only the key that ships in the game, nobody can test which players are connected.

A token of an anonymous sign-in returns 403 with the code proof_required: it verifies a device, not a player.
A connect pass is not accepted: it works once.
A game with no proof cannot make this request. If it holds a refresh token, the player is connected until Renew a player session reports otherwise.

When the response is true, send Start connect with the same proof. A player connected with their own approval at the verified level is then approved immediately, and the device gets its tokens with no Discord step.

Limits

60 requests a minute from one IP address.

Errors

Status	`code`	`error`	When
`400`	`bad_request`	`The request body must be a JSON object`	The body is `null`, text, a number or a list. A request with no `Content-Type` header is read as text, so it gets this response too
`400`	`bad_player_id`	`playerId must be 1 to 128 characters: letters, digits and . _ : @ \| + = -, starting with a letter or a digit`	`playerId` is missing, is not text, is longer than 128 characters, or contains a character that is not allowed. A number is refused
`400`	`bad_proof`	`proof must be an object with type firebase, unity or steam and a token`	`proof` is missing, or is not an object with a `type` of `firebase`, `unity` or `steam` and a `token` of 1 to 4,096 characters
`400`	`bad_proof`	`proof must be an object with a type and a token`	The game has no project saved for the sign-in service `proof.type` names
`401`	`proof_rejected`	`The proof of the player was not accepted`	The token was not accepted. The body adds `reason`: `signature`, `expired`, `wrong_player`, `wrong_project`, or `too_old` for a token issued more than 10 minutes ago
`503`	`proof_service_unavailable`	`The proof could not be checked right now. Try again`	The keys of Firebase or Unity could not be fetched to check the token. Retry
`403`	`proof_required`	`Only a game that has proven the player can ask whether the player is connected`	The token is of an anonymous sign-in, which identifies a device, not a player

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.