ggbucks.docs
Developer portal

Native linking

Inspect a linking request in the native consent flow

Native ggbucks app only. Require a verified native Clerk session for an active account and the native device admission policy. In enforce mode, send challenge-v1 capability and a live device permit bound to this exact session; an approved different session is insufficient. Client headers cannot create a permit. The native app must satisfy minimum-build policy when enabled. Returns game name, external player identifier and expiry for consent; it does not bind the player. Expired, consumed, paused or revoked-key intents are rejected.

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

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/inspect" \
  -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": {
    "expiresAt": "2026-10-11T12:00:00.000Z",
    "externalPlayerId": "studio-player-42",
    "gameName": "Example Puzzle",
    "mode": "sandbox"
  }
}
dataobjectrequired
  • Unknown fields are rejected
Show nested fields
expiresAtstring · date-timerequired
externalPlayerIdstringrequired
  • At least 1 characters
  • Up to 200 characters
  • Pattern: ^[^\u0000-\u001f\u007f]*$
gameNamestringrequired
mode"sandbox"required

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