クイックスタート

全体の流れ

Cloud Auth は「利用者のサインイン」と「サービス間の通信」を分けて扱います。 利用者はメールアドレスとパスワード（必要に応じて二段階認証）でサインインし、 アクセストークンを受け取ります。あなたのサーバーは API キーを使って そのトークンを検証したり、アカウントを管理したりします。

利用者のブラウザ／アプリ            あなたのサーバー
        │                              │
        │ 1. Login (email, password)   │
        ├──────────────► Cloud Auth ◄──┤ 3. VerifyToken (X-API-Key)
        │ 2. access_token              │
        ├──────────────────────────────►│  トークンを添えてAPIを呼ぶ

1. API キーを発行する

管理画面の「API キー」から、用途がわかる名前を付けて発行します。 シークレットは発行直後の一度しか表示されません。 キーは発行したアカウントの権限を引き継ぐため、必要最小限の権限を持つ アカウントで発行してください。

2. 利用者をサインインさせる

エンドポイントはすべて POST で、JSON を受け取り JSON を返します。

curl -X POST https://api.albos.org/auth.v1.AuthService/Login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

# 応答（二段階認証が無効な場合）
{
  "user": { "id": "...", "email": "[email protected]", "role": "USER_PRIMARY" },
  "tokens": {
    "accessToken": "eyJhbGci...",
    "refreshToken": "...",
    "expiresIn": "900"
  }
}

# 応答（二段階認証が有効な場合）
{ "requiresTwoFactor": true, "twoFactorToken": "..." }

requiresTwoFactor が返ってきた場合は、利用者に6桁のコードを 入力してもらい、VerifyTwoFactor を呼び出します。

curl -X POST https://api.albos.org/auth.v1.AuthService/VerifyTwoFactor \
  -H "Content-Type: application/json" \
  -d '{"twoFactorToken":"...","code":"123456"}'

3. 受け取ったトークンを検証する

あなたのサーバーが利用者からアクセストークンを受け取ったら、 API キーを添えて検証します。署名・有効期限だけでなく、 ログアウト済みか、アカウントが無効化されていないかまで判定されます。

curl -X POST https://api.albos.org/auth.v1.AuthService/VerifyToken \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ca_..." \
  -d '{"accessToken":"eyJhbGci..."}'

# 応答
{
  "active": true,
  "user": { "id": "...", "email": "[email protected]", "role": "USER_PRIMARY" },
  "sessionId": "...",
  "role": "USER_PRIMARY",
  "expiresAt": "1789000000"
}

4. トークンを更新する

アクセストークンの寿命は15分です。切れたらリフレッシュトークンで更新します。 ブラウザからは Cookie が自動送信されるため本文は空で構いません。 モバイルアプリからは本文に含めて送ります。

curl -X POST https://api.albos.org/auth.v1.AuthService/RefreshToken \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"..."}'

ブラウザから直接呼ぶ場合

Cookie による認証を使う場合、リクエスト元のオリジンを許可リストに 登録する必要があります。運用者に連絡してください。 また、Cookie を送るには credentials: "include" の指定が必要です。

const res = await fetch("https://api.albos.org/auth.v1.AuthService/GetCurrentUser", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
  body: "{}",
});