Game SDK
Create a native account linking intent
Your trusted game server creates a player from its stable external identifier and a one-time 10-minute token. Send the token to the native ggbucks consent flow using ggbucks://developer-game-link?linkToken=<token>. Treat it as a secret: never log or persist it in analytics, browser history or untrusted storage. Already linked players and paused games are rejected. Repeated intent creation is not event-style idempotency and may create another token.
POST
/api/game-sdk/v2/linksAuthentication
Game server secretSecret game server credential. Keep it on a trusted server; never ship it in Unity, a browser, mobile binaries or public repositories. Public keys are rejected for writes. Revoked secrets are rejected.
# Illustrative request only. Replace IDs/tokens; events need a current occurredAt.
# Native examples require an already admitted native session/device permit.
curl --fail-with-body --max-time 15 -X POST \
"https://api.ggbucks.com/api/game-sdk/v2/links" \
-H "Authorization: Bearer ${GGBUCKS_GAME_SECRET}" \
-H "Content-Type: application/json" \
--data '{"externalPlayerId":"studio-player-42"}'Illustrative examples; replace placeholders. Trusted game server only. Keep the secret in its secret manager.
Request body
{
"externalPlayerId": "studio-player-42"
}externalPlayerIdstringrequired- At least 1 characters
- Up to 200 characters
- Pattern: ^[^\u0000-\u001f\u007f]*$
Unknown fields are rejected.
Responses
200Successful sandbox response.
application/json
{
"data": {
"expiresAt": "2026-10-11T12:00:00.000Z",
"linkToken": "ggb_link_sandbox_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"mode": "sandbox",
"playerId": "11111111-1111-4111-8111-111111111111"
}
}dataobjectrequired- Unknown fields are rejected
Show nested fields
expiresAtstring · date-timerequiredlinkTokenstringrequiredIllustrative repeated-A examples are inert. A real token is secret, one-time and expires after 10 minutes.
- Pattern: ^ggb_link_sandbox_[A-Za-z0-9_-]{43}$
mode"sandbox"requiredplayerIdstring · uuidrequiredUnknown fields are rejected.
Unknown fields are rejected.
400Invalid request or allocation/cap constraint.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.
401Missing or invalid credential/token.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.
403Admission or organization permission denied.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.
404Scoped resource not found.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.
409Replay conflict, expired link or incompatible resource state.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.
413JSON body exceeds 16,384 UTF-8 bytes.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.
415Content-Type must be application/json.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.
503Platform disabled or admission/database dependency temporarily unavailable; no successful mutation is implied.
application/json
errorobjectrequired- Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"requiredmessagestringrequiredUnknown fields are rejected.
Unknown fields are rejected.