[2026-04-16] C-583: Document S2S player session endpoint v2/identify#5
Open
[2026-04-16] C-583: Document S2S player session endpoint v2/identify#5
Conversation
Add API documentation for the server-to-server identify endpoint covering
request payload (game_id, secret_key, user_id, timezone, client_ip,
deep_link), success response (201 with player data, opt-out states,
player properties, templated deep links), and error responses (403, 404).
## Human-Claude Interaction Log
### Human prompts (VERBATIM):
1. "Take a look at ../server-api-docs and sketch out the request payload and response payload for this new API call form."
→ Claude: Explored the server-api-docs repo structure (Antora/AsciiDoc), read existing endpoint docs for conventions, then sketched out request and response payloads in markdown for review.
2. "Go ahead and update the docs."
→ Claude: Created modules/ROOT/pages/other/v2_identify.adoc following the existing AsciiDoc conventions (metadata table, parameter tables, nested response field tables, error response partials). Added nav entry.
3. "Commit your work."
→ Claude: Committed the documentation changes.
### Key decisions made:
- Human guided: write the docs in server-api-docs repo following existing conventions
- Claude discovered: existing docs use AsciiDoc/Antora with specific table formatting, response partials, and xref cross-references; 404 error format differs from other endpoints (uses {error:{code,message}} not {status,errors})
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds Antora/AsciiDoc documentation for the server-to-server POST v2/identify endpoint so integrators can understand required/optional request parameters, the 201 success payload, and the 403/404 error formats.
Changes:
- Added a new endpoint doc page for
v2/identify, including request parameters, example request, success response schema/example, and error responses. - Added the new page to the “Other” section navigation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| modules/ROOT/pages/other/v2_identify.adoc | New documentation page for the S2S player session identify endpoint (v2/identify). |
| modules/ROOT/nav.adoc | Adds the new v2_identify doc page to the sidebar nav. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…(C-583) Strip id, game_id, and user_profile fields from the documented response to match the implementation change avoiding exposure of internal numeric IDs and internal data structures. ## Human-Claude Interaction Log ### Human prompts (VERBATIM): 1. "Feedback on the API: I'd rather not return numeric game id/user id... Let's also cut user_profile from the login s2s response." → Claude: Updated docs to remove id, game_id, user_profile from response fields and example JSON. 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
- Add session_id to response fields and example - Document 200 req/sec rate limit with 429 error response - Add NOTE about permanent opt-out behavior (session created but no tokens stored) ## Human-Claude Interaction Log ### Human prompts (VERBATIM): 1. "Let's include session_id in the output, and update the docs accordingly. Let's rate limit to 200 req/sec, but only for S2S calls. Let's document the permanent opt out behavior (it should be documented elsewhere but overcommunicating and putting information at the point of need makes for a better experience)." → Claude: Added session_id to response, :rate_limit: 200 attribute, rate limiting table row, 429 error section, and permanent opt-out NOTE. 2-7. [Rate limiting DRY-up, metrics, and commit discussions - see carrot repo commit for full log] ### Key decisions made: - Human guided: Overcommunicate opt-out behavior at point of need even if documented elsewhere 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
Add email as an optional parameter for player session creation. Include in example request payload. ## Human-Claude Interaction Log ### Human prompts (VERBATIM): 1. "Great! Now, implement the feature and update the docs." → Claude: Added email param to optional parameters table and example request in v2_identify.adoc. 2. "Commit and push your changes to both repos." → Claude: Staged and committed docs changes. ### Key decisions made: - Claude: Documented permanent opt-out interaction with email storage 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
…vior (C-583) S2S identify only accepts IANA timezone names (timezone_id), not numeric UTC offsets. Updated optional params and example request accordingly. ## Human-Claude Interaction Log ### Human prompts (VERBATIM): 1-2. [See carrot repo commit for full timezone/ad ID/client_ip discussion] 6. "Correction: Since timezone name is supported, we apparently ONLY want to support that. No offsets. Update the code and docs accordingly." → Claude: Replaced timezone + timezone_id params with just timezone_id in docs and example ### Key decisions made: - Human guided: Only timezone_id (IANA names) supported for S2S, not numeric offsets 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
Document parameter validation errors for S2S identify. All validation errors are returned in a single response. Example shows timezone_id and client_ip errors together. ## Human-Claude Interaction Log ### Human prompts (VERBATIM): 4. "Should the docs be updated to reflect the error handling changes?" → Claude: Added 400 Bad Request section with multi-error example. 5. "Change that documentation example to use an error for timezone_id, and client_ip not timezone and client_ip." → Claude: Updated example to show timezone_id + client_ip errors. 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
MrJoy
changed the title
AlexSc
requested changes
Apr 10, 2026
- Rewrite intro per Alex's feedback: "records that a player has started a session", not "creates or resumes". Each call is a new session. Drives Played event; first-time also tracks Installed. - NOTE block: "exclusion" not "data removal", "tracked" not "created", cross-link to v2_exclusions. - Section heading: "Recording a Player Session" not "Creating or Resuming". - deep_link param/response: document that Teak managed links (custom scheme or Teak link domain) are resolved to a custom scheme deep link with Liquid templating applied. Other links returned as-is. ## Human-Claude Interaction Log ### Human prompts (VERBATIM): 1. "We're going to work on this branch of carrot, and the corresponding server-api-docs branch (feat/c-583-server-to-server-login-api). There's feedback on server-api-docs PR #5, and we need to update both repos accordingly." → Claude: Fetched PR #5 feedback from AlexSc and MrJoy, summarized all comments. 2. "Question: Does the universal link resolution behavior described in the docs match what the controller is doing?" → Claude: Analyzed controller vs docs, identified 4 mismatches around launch_link/deep_link handling. 3. "In terms of universal link resolution, the docs are authoritative and the controller needs to match the docs. Let's update the docs for 1 and 2, and update the tests to match the docs." → Claude: Updated docs intro/NOTE (items 1&2), removed launch_link-based S2S tests, added deep_link resolution tests. 4. "Doesn't Alex expect the deep_link parameter to do deep link resolution?" → Claude: Re-read Alex's comments — he's asking for resolution through deep_link, not launch_link. Updated docs and tests. 5. "Are you sure the 'applies Liquid templating after resolving a universal link' test matches the documentation?" → Claude: Recognized the test was testing internal pipeline, not API contract. Removed it. 6. "Clarification from Alex: 'If it's a Teak managed link — custom scheme or universal link — we're going to give you back a custom scheme URL with templating applied.'" → Claude: Updated docs to describe two cases (Teak managed → custom scheme + templating, other → as-is). Re-added Liquid-after-resolution test since it IS the documented behavior. 7. "Update the docs and tests." → Claude: Made final docs and test updates matching Alex's clarification. 8. "Commit the changes in both repos, then update the code to pass the tests." → Claude: Committing. ### Key decisions made: - Human guided: docs are authoritative, controller must match - Human guided: Alex's clarification unified resolution + templating into one behavior for Teak managed links - Human caught: Liquid-after-resolution test was correct behavior, not just implementation detail - Claude discovered: launch_link is an SDK-internal param, not part of S2S API surface 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
Either client_ip or country_code must be provided. client_ip takes priority. New country_code param for when IP is unavailable. Updated response country_code description and 400 error example. If neither value is known, pass 127.0.0.1 for client_ip. ## Human-Claude Interaction Log ### Human prompts (VERBATIM): 1. "Next up, we need to reconcile the geolocation functionality with another S2S API we're making on a different branch. The documented behavior there, which we'd like to have parity with here is to use the first one of these that is available: 1. `client_ip` 2. `country_code` (we may need to resolve this to a `location_id` via Parsnip?) 3. The player's location from their most recent SDK session What does it take to get us there?" → Claude: Traced geolocation flow, found Parsnip endpoints, identified gaps. 2. "Actually, we're going to skip #3 here. We're also going to make a change so that we don't fall back to using the server IP if neither `client_ip` nor `country_code` is provided. One of the two MUST be provided. We need to update the docs appropriately. In the event that neither value is known or they do not want to provide it, they should pass 127.0.0.1 for `client_ip`. Let's get the docs and specs updated, shall we?" → Claude: Updated docs and tests. 3. "Great! Now, let's get the controller updated." → Claude: Implemented controller changes. 4. "Commit and push your changes to both repos." → Claude: Committing. ### Key decisions made: - Human guided: skip #3 (fallback to SDK session location), require one of client_ip/country_code - Human guided: 127.0.0.1 as the "don't know" sentinel value 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add API documentation for the server-to-server identify endpoint covering request payload (game_id, secret_key, user_id, timezone, client_ip, deep_link), success response (201 with player data, opt-out states, player properties, templated deep links), and error responses (403, 404).
Human-Claude Interaction Log
Human prompts (VERBATIM):
"Take a look at ../server-api-docs and sketch out the request payload and response payload for this new API call form." → Claude: Explored the server-api-docs repo structure (Antora/AsciiDoc), read existing endpoint docs for conventions, then sketched out request and response payloads in markdown for review.
"Go ahead and update the docs." → Claude: Created modules/ROOT/pages/other/v2_identify.adoc following the existing AsciiDoc conventions (metadata table, parameter tables, nested response field tables, error response partials). Added nav entry.
"Commit your work." → Claude: Committed the documentation changes.
Key decisions made:
🤖 Generated with Claude Code