認證

Poshen API 透過 Bearer Token 機制保護需要使用者身分的 endpoint。Token 從三種登入 endpoint 之一取得，後續所有需要驗證的請求都帶在 Authorization header 裡。

Token 怎麼帶

curl https://api.poshentw.com/users/redemptions \
  -H "Authorization: Bearer 1|aBcDeFgHiJkLm..."

Token 沒有 expire 機制（除非用戶主動登出或被刪除帳號）。建議客戶端用安全儲存（Keychain / Android EncryptedSharedPreferences）保存。

三種登入方式

Google OAuth

使用 Google ID Token 登入。客戶端先透過 Google Sign-In SDK 拿到 id_token，再送來這個 endpoint 換 Bearer Token。

必填欄位

  • Name
    id_token
    Type
    string
    Description

    Google Sign-In SDK 取得的 ID Token。

  • Name
    game_id
    Type
    integer
    Description

    遊戲識別 ID（games 表的 PK）。

選填欄位

  • Name
    game_player_id
    Type
    string
    Description

    該遊戲內的玩家識別碼（如 Unity Player ID），用來綁定 game_account。

Request

POST
/login/google
curl https://api.poshentw.com/login/google \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "id_token": "eyJhbGc...假.id.token...0XYZ",
    "game_id": 1,
    "game_player_id": "unity-12345"
  }'

Response

{
  "data": {
    "user": {
      "id": 42,
      "email": "alice@example.com",
      "name": "Alice",
      "avatar_url": null
    },
    "token": "1|aBcDeFgHiJkLm..."
  }
}

Apple OAuth

使用 Apple ID Token 登入。首次登入時 Apple 會回傳使用者姓名，需要完整帶到 user 物件中。

必填欄位

  • Name
    id_token
    Type
    string
    Description

    Apple Sign-In 取得的 ID Token。

  • Name
    game_id
    Type
    integer
    Description

    遊戲識別 ID。

選填欄位

  • Name
    game_player_id
    Type
    string
    Description

    遊戲內玩家識別碼。

  • Name
    user
    Type
    object
    Description

    首次登入時 Apple 回傳的使用者資料，含 name.firstName / name.lastName / email。

Request

POST
/login/apple
curl https://api.poshentw.com/login/apple \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "id_token": "eyJhbGc...假.apple.token...0",
    "game_id": 1,
    "user": {
      "name": { "firstName": "Bob", "lastName": "Wang" },
      "email": "bob@example.com"
    }
  }'

訪客登入

建立或取得匿名訪客帳號。Email 會被 mask 成 {uuid}@guest.com 格式。

必填欄位

  • Name
    game_id
    Type
    integer
    Description

    遊戲識別 ID。

  • Name
    game_player_id
    Type
    string
    Description

    遊戲內玩家識別碼，作為訪客帳號的唯一識別。

Request

POST
/login/guest
curl https://api.poshentw.com/login/guest \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": 1,
    "game_player_id": "unity-guest-99999"
  }'

共通行為

情況行為
第一次以該 OAuth 帳號登入自動建立新 user + game_account
同一 OAuth 帳號再次登入回傳既有 user，更新 last_login_at
OAuth Token 無效回 401（InvalidGoogleTokenException / InvalidAppleTokenException）
game_id 不存在回 404（GameNotFoundException）

Was this page helpful?