API Token

API Token は、認証が必要な ExpTech API を呼び出すときに使う資格情報で、et_ で始まります。Token はダッシュボードで作成します。作成後は有効期限がなく、取り消すまで有効です。現在公開している HTTP データ API の多くは token が不要です。各エンドポイントのページにある「認証」の節に、必要かどうかが書いてあります。

Token の作成

https://manager.exptech.com.tw/login にログインします（メールアドレスを入力し、届いたメールのログインリンクを開きます）。
ダッシュボードの API Token ページを開きます。
この token に必要な権限を選びます。メモを書いてもかまいません（最大 15 文字）。
作成すると、画面に完全な token が表示されます。Token が表示されるのはこの一度だけです。 すぐに安全な場所へ保存してください。その後の一覧ではメモと権限だけが見え、token 自体は見えません。

Token の形式と有効期限

形式：et_ に 43 文字の base64url（A–Z、a–z、0–9、-、_）が続きます。例：et_3q2-7wAAexampleexampleexampleexampleexample。
有効期限：期限はなく、refresh token もありません。取り消されない限り有効です。
サーバーが保存するのは token のハッシュだけです。紛失しても取り戻せないので、新しく作成してください。

Token の付け方

伝送のしかたによって token を読む場所が違います。場所を間違えると、付いていないものとして扱われます。

用途	付け方	説明
HTTP API（ページに token が必要と書いてあるエンドポイント）	header `X-Api-Token: <token>`	この header だけを読みます。query や `Authorization` に置くと 401 になります
SSE リアルタイム配信	header `Authorization: Bearer <token>`、または query `token=<token>`	両方あるときは header を優先します。`Bearer` は大文字と小文字をこのとおりにし、うしろに空白を 1 つ置きます
OAuth2 のユーザー情報	header `Authorization: Bearer <token>`

HTTP

GET /api/... HTTP/1.1
X-Api-Token: et_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

SSE 配信

header を付けられるクライアント（サーバー、アプリ、curl）は header を使ってください。

curl -N -H "Authorization: Bearer et_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.lb.exptech.dev/api/v1/trem/sse/report"

ブラウザの EventSource は header を付けられないため、query に置くしかありません。

const token = "et_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const es = new EventSource(
  `https://api.lb.exptech.dev/api/v1/trem/sse/report?token=${encodeURIComponent(token)}`,
);

配信の topic には公開のものがあり、token なしでも接続できます。token を付けると、利用量はそのアカウントに計上されます。無効な token や取り消し済みの token を付けると、接続全体が拒否されます（HTTP 401、本文 invalid token）。公開 topic も同じです。権限が必要な topic では、token に対応する権限があり、かつアカウントがそのリソースを購読している必要があります。各 topic の規則はリアルタイム配信を参照してください。

Token の取り消し

ダッシュボードの API Token ページで削除します。現在、「token 自体を渡して取り消す」API はありません。

HTTP：取り消し後、最大で約 1 分以内に完全に無効になります。
SSE：取り消しの約 5 秒後、そのアカウントの token で認証した配信接続のすべてが event: close、data: token revoked を受け取って閉じられます。取り消された token の接続だけではありません。まだ有効な別の token で接続し直してください。

セキュリティ上の推奨

token をフロントエンドのコード、アプリのインストールファイル、公開された Git リポジトリに書かないでください。
用途ごとに token を分け、メモには使う場所を書いてください。漏えいしたときは、その 1 つだけを取り消せます。
権限は必要なものだけを選んでください。*（すべての権限）はテストには便利ですが、漏えいしたときの影響が最も大きくなります。