認証

認証

ZenFlip APIは2つの認証方法をサポートしています：メール/パスワードログイン（JWTトークン）とGoogle OAuthです。サーバー間通信用のAPIキーは近日対応予定です。すべての保護されたエンドポイントでは、Authorizationヘッダーに有効なBearerトークンが必要です。

メールとパスワードによるログイン

サインアップ

新しいアカウントと組織を作成します：

`bash curl -X POST https://api.zenflip.io/v1/auth/signup \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!", "name": "Alex Chen", "organizationName": "Acme Publishing" }' `

サインアップ後、確認メールが送信されます。フルアクセスが許可される前にアカウントの確認が必要です。

ログイン

認証情報をJWTトークンと交換します：

`bash curl -X POST https://api.zenflip.io/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!" }' `

レスポンス：

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600, "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "developer@example.com", "name": "Alex Chen", "role": "owner", "emailVerified": true }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Acme Publishing", "plan": "creator" } } `

accessTokenはexpiresInで示された秒数後に期限切れになります（デフォルト：3600秒 / 1時間）。refreshTokenはより長い有効期間を持ち、認証情報を再入力せずに新しいアクセストークンを取得するために使用されます。

トークンの使用

すべての保護されたリクエストでAuthorizationヘッダーにアクセストークンを含めます：

`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." `

JavaScript fetchを使用する場合：

`javascript const response = await fetch("https://api.zenflip.io/v1/publications", { headers: { "Authorization": Bearer ${accessToken}, "Content-Type": "application/json" } }); const { data, meta } = await response.json(); `

トークンリフレッシュ

アクセストークンが期限切れになった場合、リフレッシュトークンを使用して、ユーザーに再ログインを求めることなく新しいトークンペアを取得します：

`bash curl -X POST https://api.zenflip.io/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }' `

レスポンス：

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600 } `

リフレッシュ呼び出しのたびに、アクセストークンとリフレッシュトークンの両方がローテーションされます。新しいリフレッシュトークンを保存し、古いものを破棄してください。ZenFlipウェブダッシュボードを使用している場合、トークンは自動的にhttpOnlyクッキーとしても設定されます。

JavaScriptリフレッシュ例

`javascript async function refreshAccessToken(currentRefreshToken) { const response = await fetch("https://api.zenflip.io/v1/auth/refresh", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ refreshToken: currentRefreshToken }) });

if (!response.ok) { throw new Error("Token refresh failed, user must re-authenticate"); }

const tokens = await response.json(); // tokens.accessTokenとtokens.refreshTokenを安全に保存 return tokens; } `

Google OAuth

ZenFlipはシングルサインオン用にGoogle OAuthをサポートしています。このフローはブラウザベースで、サーバーサイドリダイレクトを使用します。

フロー

1. ユーザーをhttps://api.zenflip.io/v1/auth/googleにリダイレクトします。

2. ユーザーがGoogleで認証し、同意を付与します。

3. Googleがhttps://api.zenflip.io/v1/auth/google/callbackにリダイレクトします。

4. APIがhttpOnly認証クッキーを設定し、ユーザーをフロントエンドのコールバックURL（例：https://app.zenflip.io/auth/google/callback?isNew=0）にリダイレクトします。

isNewパラメータは、新しいアカウントが作成されたか（1）、既存のアカウントにログインしたか（0）を示します。フロントエンドはこのフラグを読み取って、オンボーディングを表示するかどうかを判断します。

統合例

`html <a href="https://api.zenflip.io/v1/auth/google" class="btn-google"> Googleでサインイン </a> `

OAuthコールバック後、ユーザーのブラウザには認証クッキーが設定されています。ブラウザからの以降のAPI呼び出しは、これらのクッキーを介して認証されます。

APIキー（サーバー間通信） — 近日対応予定 {#api-keys}

バックエンド統合、Webhook、またはCI/CDパイプラインの場合、APIキーはログイン/リフレッシュフローを必要としない、よりシンプルな認証パスを提供します。それまでは、すべてのAPIアクセスにJWTトークンを使用してください。

メール確認

新しいアカウントにはメール確認が必要です。APIは確認と確認メールの再送信のためのエンドポイントを提供しています：

`bash

メールリンクのトークンで確認

curl -X POST https://api.zenflip.io/v1/auth/verify-email \ -H "Content-Type: application/json" \ -d '{ "token": "verification-token-from-email" }'

確認メールの再送信

curl -X POST https://api.zenflip.io/v1/auth/resend-verification \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }' `

パスワードリセット

ユーザーがパスワードを忘れた場合、リセットフローを開始します：

`bash

パスワードリセットメールのリクエスト

curl -X POST https://api.zenflip.io/v1/auth/forgot-password \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }'

メールのトークンでパスワードをリセット

curl -X POST https://api.zenflip.io/v1/auth/reset-password \ -H "Content-Type: application/json" \ -d '{ "token": "reset-token-from-email", "password": "NewSecureP@ssw0rd!" }' `

現在のユーザープロフィール

認証済みユーザーのプロフィールを取得します：

`bash curl https://api.zenflip.io/v1/auth/me \ -H "Authorization: Bearer YOUR_TOKEN" `

ログアウト

現在のセッションを無効化し、クッキーをクリアします：

`bash curl -X POST https://api.zenflip.io/v1/auth/logout \ -H "Authorization: Bearer YOUR_TOKEN" `

レート制限

認証エンドポイントには、不正利用を防止するための独自のレート制限があります：