REST API

Detailed documentation of all Fetamix API endpoints, authentication methods, and error codes.

API overview

Live

Base URL: https://api.fetamix.com/api/v1
Authentication: Bearer Token (JWT)
Response format: JSON
Encoding: UTF-8

Sandbox

Base URL: https://api-sandbox.fetamix.com/api/v1
Site URL: https://sandbox.fetamix.com
Authentication: Bearer Token (JWT)
Response format: JSON

In-game authentication API

API link summary

Live

In-game login start (web path):
https://fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&client=game
Token verification (API):
GET https://api.fetamix.com/api/v1/game/auth/verify

Sandbox

In-game login start (web path):
https://sandbox.fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&sandbox_game_id=SANDBOX_GAME_ID
Token verification (API):
GET https://api-sandbox.fetamix.com/api/v1/game/auth/verify

In-game token payload

The JWT payload issued on in-game login completion is as follows.

Example

{
  "sub": 1,
  "type": "app",
  "game_id": 1,
  "device_key": "android_abcdef-1234-...",
  "iat": 1761714925
}

Field description

sub: User ID (number)
type: Fixed value "app"
game_id: Game ID (live: number, sandbox: string, e.g. "1_10000")
device_key: Device identifier (e.g. Android device ID)
iat: Issued at (Unix epoch, seconds). exp is not included.

OAuth authentication (first login)

Used only for first install or when no token exists. When the game has no token, the user is sent to the login page in an external browser. The client parameter indicates in-game context.

Open in external browser

Live:

https://fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&client=game

Sandbox:

https://sandbox.fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&sandbox_game_id=SANDBOX_GAME_ID

After login, the user is redirected back to the Unity app via deep link with auth data.
Enter the client secret issued for your game in the client_secret parameter.
The key parameter contains device-specific info (e.g. Android device ID).
Sandbox Sandbox requires the sandbox_game_id parameter.

Deep link scheme example

// Deep link scheme registered in Unity app (token only)
fetamix://ingame-login?token=JWT_TOKEN

// JWT (type: "app") contains in-game identity info

Handle this scheme in Unity to receive and store the JWT. The game client only needs to store the token.

In-game login

Used when a client that already has a valid token is restarted. This API verifies the token when the game starts.

Token verification API

Live:

GET https://api.fetamix.com/api/v1/game/auth/verify
Authorization: Bearer YOUR_ACCESS_TOKEN

Sandbox:

GET https://api-sandbox.fetamix.com/api/v1/game/auth/verify
Authorization: Bearer YOUR_ACCESS_TOKEN

For in-game, verifying the stored JWT without URL parameters is sufficient. The server also checks device_key. On failure (401 or device mismatch), switch to the first-login flow.

Response

{
  "success": true,
  "data": {
    "valid": true,
    "sub": 1,
    "type": "app",
    "game_id": 1,
    "device_key": "android_abcdef-1234-...",
    "iat": 1761714925,
    "exp": 4825056125
  }
}

The server returns the full JWT payload, so the game client can use sub, game_id, and device_key for additional validation or logging.

In Sandbox, data.game_id is a string (e.g. "1_10000"). In live it is a number.

⚠️ Security note

You must call the token verification API when the game starts. You cannot start the game with only the token; the game may start only after the server confirms the token is valid.

// ❌ Wrong: starting game with token only
if (!string.IsNullOrEmpty(accessToken))
{
    StartGame(); // Security risk!
}

// ✅ Correct: verify token then start game
if (!string.IsNullOrEmpty(accessToken))
{
    // Call token verification API
    // VerifyTokenAndStartGame(); (use when available)
}

🔒 Device-bound security

When issuing the JWT, device-specific info is combined so the token can only be used on that device.

Android

Pass device ID in the key parameter

Effect: If the token is copied to another device, the server will reject it due to device mismatch.

In-game client

• Token type: type: "app"
• Use cases: Unity app, mobile app, in-game

Error codes

Code	Status	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Authentication failed or token expired
403	Forbidden	Access denied
404	Not Found	Resource not found
500	Internal Server Error	Internal server error

In-game authentication API

API link summary

Live

In-game login start (web path):
https://fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&client=game
Token verification (API):
GET https://api.fetamix.com/api/v1/game/auth/verify

Sandbox

In-game login start (web path):
https://sandbox.fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&sandbox_game_id=SANDBOX_GAME_ID
Token verification (API):
GET https://api-sandbox.fetamix.com/api/v1/game/auth/verify

In-game token payload

The JWT payload issued on in-game login completion is as follows.

Example

{
  "sub": 1,
  "type": "app",
  "game_id": 1,
  "device_key": "android_abcdef-1234-...",
  "iat": 1761714925
}

Field description

sub: User ID (number)
type: Fixed value "app"
game_id: Game ID (live: number, sandbox: string, e.g. "1_10000")
device_key: Device identifier (e.g. Android device ID)
iat: Issued at (Unix epoch, seconds). exp is not included.

OAuth authentication (first login)

Used only for first install or when no token exists. When the game has no token, the user is sent to the login page in an external browser. The client parameter indicates in-game context.

Open in external browser

Live:

https://fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&client=game

Sandbox:

https://sandbox.fetamix.com/ingame-login?client_secret=YOUR_CLIENT_SECRET&key=DEVICE_KEY&sandbox_game_id=SANDBOX_GAME_ID

Deep link scheme example

// Deep link scheme registered in Unity app (token only)
fetamix://ingame-login?token=JWT_TOKEN

// JWT (type: "app") contains in-game identity info

Handle this scheme in Unity to receive and store the JWT. The game client only needs to store the token.

In-game login

Used when a client that already has a valid token is restarted. This API verifies the token when the game starts.

Token verification API

Live:

GET https://api.fetamix.com/api/v1/game/auth/verify
Authorization: Bearer YOUR_ACCESS_TOKEN

Sandbox:

GET https://api-sandbox.fetamix.com/api/v1/game/auth/verify
Authorization: Bearer YOUR_ACCESS_TOKEN

For in-game, verifying the stored JWT without URL parameters is sufficient. The server also checks device_key. On failure (401 or device mismatch), switch to the first-login flow.

Response

{
  "success": true,
  "data": {
    "valid": true,
    "sub": 1,
    "type": "app",
    "game_id": 1,
    "device_key": "android_abcdef-1234-...",
    "iat": 1761714925,
    "exp": 4825056125
  }
}

The server returns the full JWT payload, so the game client can use sub, game_id, and device_key for additional validation or logging.

In Sandbox, data.game_id is a string (e.g. "1_10000"). In live it is a number.

⚠️ Security note

You must call the token verification API when the game starts. You cannot start the game with only the token; the game may start only after the server confirms the token is valid.

// ❌ Wrong: starting game with token only
if (!string.IsNullOrEmpty(accessToken))
{
    StartGame(); // Security risk!
}

// ✅ Correct: verify token then start game
if (!string.IsNullOrEmpty(accessToken))
{
    // Call token verification API
    // VerifyTokenAndStartGame(); (use when available)
}

🔒 Device-bound security

When issuing the JWT, device-specific info is combined so the token can only be used on that device.

Android

Pass device ID in the key parameter

Effect: If the token is copied to another device, the server will reject it due to device mismatch.

In-game client

• Token type: type: "app"
• Use cases: Unity app, mobile app, in-game

Code

Status

Description

400

Bad Request

Invalid request parameters

401

Unauthorized

Authentication failed or token expired

403

Forbidden

Access denied

404

Not Found

Resource not found

500

Internal Server Error

Internal server error