ggbucks.docs
Developer portal

Native linking

Approve linking after native user consent

Native ggbucks app only, with the same session, account and device admission preconditions as inspection. Invoke after explicit user consent. Binds the game player to the canonical active native account, consumes the token and forbids rebinding. A consumed token replay by the same account returns the original approved state; a different account is denied. An unconsumed expired token, paused game or revoked issuing key is rejected. Linking is independent of developer dashboard invitations and does not credit a wallet.

POST/api/v0/game-sdk/v2/links/approve

Authentication

Native app session

Native ggbucks account session, subject to supported-country admission, active account, minimum native build and exact-session device permit admission. A country admission denial returns GEO_BLOCKED before the linking operation. In enforce mode capability challenge-v1 and a live permit bound to this same session are required. The permit is established by the native device verification flow, outside this public SDK contract.

Native app owned
These endpoints require the compatible ggbucks app's authenticated session and device admission. Game developers must not collect player session tokens or automate native approval.
# 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/v0/game-sdk/v2/links/approve" \
  -H "Authorization: Bearer ${GGBUCKS_NATIVE_SESSION}" \
  -H "x-ggbucks-device-auth-capability: challenge-v1" \
  -H "Content-Type: application/json" \
  --data '{"linkToken":"ggb_link_sandbox_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}'

Illustrative examples; replace placeholders. Native app diagnostics with an already admitted ggbucks session. Never collect player sessions or approve consent on a game server.

Parameters

x-ggbucks-device-auth-capabilityheaderoptional

Required by device enforcement mode. Declares native capability; it does not authenticate or create a device permit.

"challenge-v1"
x-ggbucks-client-versionheaderoptional

Native client version used by admission policy.

string
x-native-platformheaderoptional

Native platform. Required when native minimum-build admission is enabled.

"ios" | "android"
x-native-distheaderoptional

Native release/build distribution identifier evaluated by minimum-build policy. Use the value supplied by the supported native app.

string

Request body

{
  "linkToken": "ggb_link_sandbox_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
linkTokenstringrequired
  • At least 32 characters
  • Up to 200 characters

Unknown fields are rejected.

Responses

200Successful sandbox response.

application/json

{
  "data": {
    "gameId": "11111111-1111-4111-8111-111111111111",
    "linked": true,
    "mode": "sandbox",
    "playerId": "11111111-1111-4111-8111-111111111111"
  }
}
dataobjectrequired
  • Unknown fields are rejected
Show nested fields
gameIdstring · uuidrequired
linkedtruerequired
mode"sandbox"required
playerIdstring · uuidrequired

Unknown fields are rejected.

Unknown fields are rejected.

400Invalid request or allocation/cap constraint.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

401Missing or invalid credential/token.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

403Admission or organization permission denied.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

404Scoped resource not found.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

409Replay conflict, expired link or incompatible resource state.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

413JSON body exceeds 16,384 UTF-8 bytes.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

415Content-Type must be application/json.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

426Native app/device capability update required before execution.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired

503Platform disabled or admission/database dependency temporarily unavailable; no successful mutation is implied.

application/json

Accepted shape 1

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"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

Accepted shape 2

errorobjectrequired
Show nested fields
code"ACCOUNT_DISABLED" | "ACCOUNT_STATUS_UNAVAILABLE" | "CLIENT_UPDATE_REQUIRED" | "DEVICE_ACCOUNT_CONFLICT" | "DEVICE_AUTH_UNAVAILABLE" | "DEVICE_VERIFICATION_REQUIRED" | "GEO_BLOCKED" | "INVALID_TOKEN" | "INVALID_TOKEN_PAYLOAD" | "UNAUTHORIZED"required
messagestringrequired