跳到內容

身份驗證

App 不持有用來簽發 token 的憑證。後端才持有。tokenProvider 交回下一個 bearer。後端用 server key 呼叫 YAS。

  1. SDK 呼叫 tokenProvider。
  2. App 呼叫自己的後端。
  3. 後端用 server key 呼叫 POST /v1/vehicles/tokens。POST /v1/tokens 已棄用。
  4. YAS 交回 accessToken 與 expiresAt。
  5. tokenProvider 把這兩個值交回 SDK。

30 秒內交回 accessToken 與 expiresAt。expiresAt 必須原樣交回 YAS 返回的值。只有第一次 completion 算數。以下都是失敗:30 秒內沒有 completion、token 是 null 或空字串、token 與上一條相同、SDK 讀不到 expiresAt,或 expiresAt 已經過去。iOS 上,token 含有換行也是失敗。token 必須對應這次 setup 的 partnerId、driverId 與 vehicleId。對不上會被拒絕。

tokenProvider 失敗時,記錄繼續,紀錄留在手機。行程結束時仍要呼叫 endTrip。

Server key 不會進入 App。後端也用同一條 key 呼叫 POST /v1/vehicles/trips/end(beta)。POST /v1/trips/end 已棄用。

tokenProvider 先問你們的後端,再交回 bearer。裡面不要彈出介面。

tokenProvider: { completion in
// completion(accessToken, expiresAt)
// completion(nil, nil) on failure.
}
呼叫者 後端
Header Authorization: Bearer <serverKey>
內容 partnerId、driverId、vehicleId
成功 accessToken、expiresAt、tokenType(Bearer)
失敗 內容是 { "error": "<code>" }。內容不是 JSON object、partnerId 不符合 ^[a-z0-9-]{1,64}$,或缺少 driverId、vehicleId 或它們是空字串,是 400 invalid_body。沒有 server key 或 key 不對,是 401 invalid_credentials。這次呼叫不在 server key 的範圍內,是 403 forbidden。partnerId 與 server key 不符,是 403 identity_mismatch。格式檢查先於合作夥伴配對。
終端機
curl https://api.example.yas/v1/vehicles/tokens \
-H "authorization: Bearer $SERVER_KEY" \
-H "content-type: application/json" \
-d '{"partnerId":"partner","driverId":"drv_example","vehicleId":"veh_example"}'

成功回應:

{
"accessToken": "eyJexample",
"expiresAt": "2026-10-16T12:00:00.000Z",
"tokenType": "Bearer"
}

Token 有效 24 小時。

下一步:權限。

呼叫 Supabase-hosted API 中較多資料庫操作的功能時,建議送 x-region: ap-southeast-1,讓執行區域靠近新加坡資料庫。可從回應的 x-sb-edge-region 核對。指定區域會停用自動跨區 failover;區域故障時須改動或移除該 header。此 header 只用於 API 呼叫,不用於回傳的 Storage URL 上傳。參閱 Supabase regional invocation。