Authorize User API behavior: nonce, player creation/upsert, and player_info

The POST /s2s/v1/users/authorize endpoint can be used both to generate a secure login URL for a specific player_id and to create or update that player record via player_info.

Is nonce required?

No. For server-to-server integrations, calling Authorize User without nonce is supported and safe.

• nonce is intended for the desktop QR-code authorization flow.

• If you omit nonce in a normal S2S flow, the API still returns a valid login URL.

How secure is the returned login URL?

The response contains a signed, single-use login URL that is cryptographically bound to the player_id in your request.

• Clients cannot forge or tamper with this URL to log in as a different player.

• This is the recommended secure alternative to raw deep-link patterns such as ?player_id=<id>.

Does Authorize User create players?

Yes. Authorize User performs get-or-create behavior on player_id.

• If the player does not exist yet, the endpoint creates the player.

• If the player already exists, the endpoint authorizes that existing player.

By contrast, Update Player returns 404 for non-existent players and cannot be used to pre-create a player.

Can I send player data in the same request?

Yes. The endpoint supports an optional player_info object in the request body.

{
  "player_id": "han-solo-42",
  "player_info": {
    "name": "Han Solo",
    "avatar_url": "https://example.com/han.png",
    "attributes": {
      "hard_currency_amount": 500
    },
    "custom_attributes": {
      "faction": "rebel"
    }
  }
}

player_info fields

• name — string. Player display name.

• avatar_url — string URL. Player avatar image URL.

• attributes — object. Persistent player attributes, using the same schema as Create Order.

• custom_attributes — object. Free-form key/value pairs for game-specific data.

Current upsert behavior

Authorize User now supports full upsert behavior for player_info.

• If the player does not exist, the player is created and the provided player_info is applied.

• If the player already exists, the provided player_info is also applied during the same call.

Because of this, a separate Update Player call after Authorize User is no longer required when you want to create a login URL and update player profile data in one flow.

Are segments supported in player_info?

No. This is intentional.

• player_info is limited to profile data owned by the game: name, avatar_url, attributes, and custom_attributes.

• Segments are treated as a derived concept on the platform side.

• Segments are assigned automatically by segmentation rules based on attributes, custom attributes, and player behavior, or managed through the /v1/segments S2S endpoints.

• The player’s segments are returned in the verify-player webhook response after authorization.

Recommended integration pattern

1. Call POST /s2s/v1/users/authorize with player_id and optional player_info.

2. Use the returned signed, single-use login URL to authenticate the player securely.

3. Rely on platform segmentation rules or the segments API if you need segment membership management.

4. Read resulting segment membership from the verify-player webhook if needed.