Authentication

GamifyHost uses two types of API keys. Each key type grants access to a different set of endpoints.

SDK Public Key (Client-Side)

Used by the embeddable widget and mobile SDKs. Safe to include in client-side code.

Header	Format	Example
X-API-Key	pk_test_* / pk_live_*	pk_live_4e1baec9e705789eebc174f4eabc875a

Grants access to:

• GET /v1/games
• GET /v1/games/:gameType/config
• POST /v1/games/play
• GET /v1/leaderboard
• GET /v1/users/:userId/sdk-balance
• GET /v1/users/:userId/plays

API Secret Key (Server-Side)

Used for backend-to-backend integration. Never expose in client-side code.

Header	Format	Example
X-API-Secret	sk_test_* / sk_live_*	sk_live_a3b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2

Grants access to:

• POST /v1/points/award
• GET /v1/users/:userId/balance
• GET /v1/users/:userId/history

Environments

The key prefix determines the environment:

Prefix	Environment	Description
pk_test_ / sk_test_	TEST	Sandbox data, no real rewards
pk_live_ / sk_live_	LIVE	Production data, real rewards

Test and live data are fully isolated. A test key cannot access live data and vice versa.

Error Responses

All authentication errors follow the standard envelope:

{
  "message": "Missing X-API-Key header",
  "code": 401,
  "status": "error"
}

Code	Message
401	Missing X-API-Key / X-API-Secret header
401	Invalid API key
403	API key has been revoked
403	Application is not active
403	Partner account not found

Response Format

All API responses use a standard envelope:

{
  "message": "Description of the result",
  "code": 200,
  "status": "success",
  "data": { },
  "meta": { }
}

Field	Type	Description
message	string	Human-readable result description
code	integer	HTTP status code
status	string	"success" or "error"
data	object or array	Response payload (absent on errors)
meta	object	Pagination info (only on paginated endpoints)

Pagination

Paginated endpoints accept page (default 1) and limit (default 20) query parameters and return:

{
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}