メインコンテンツまでスキップ
バージョン: 0.9.0 (最新)

🔐 認証サービス

Testing Status

Authentication Serviceは、JWTベースのセキュリティとCookieサポートを備えた、アイデンティティ登録、ログイン、ログアウト、トークン管理のための完全な認証システムを提供します。

🚀 クイックスタート​

import express from 'express';
import { services, middlewares, types, drivers } from '@nodeblocks/backend-sdk';

const { withMongo, createGoogleOAuthDriver, createTwitterOAuthDriver, createLineOAuthDriver } = drivers;
const connectToDatabase = withMongo('mongodb://localhost:27017', 'dev', 'user', 'password');

express()
  .use(
    services.authService(
      {
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('onetimetokens')),
        ...(await connectToDatabase('invitations')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        maxFailedLoginAttempts: 5,
        accessTokenExpireTime: '2h',
        refreshTokenExpireTime: '2d',
        isMfaEnabled: false,  // 多要素認証を有効化
        mfaCodeLength: 6,     // MFAコードの長さ（デフォルト: 6）
        mfaTokenExpireTime: '10m',  // MFAトークンの有効期限（デフォルト: 10m）
        mfaCodeEmailConfig: {  // isMfaEnabledがtrueの場合必須
          sender: 'noreply@example.com',
          emailConfig: {
            subject: 'Your MFA Code',
            bodyTemplate: 'Your verification code is: ${code}'
          }
        },
        verifyEmailConfig: {
          enabled: true,
          emailConfig: {
            bodyTemplate: 'Hello {{email}}',
            subject: 'Welcome to our app',
            urlTemplate: 'https://example.com/verify-email?token={{token}}',
          },
          sender: 'noreply@example.com'
        },
        invitation: {
          enabled: true,
          emailConfig: {
            bodyTemplate: '<h1>You\'re invited!</h1><p>Click <a href="{{url}}">here</a> to accept the invitation.</p>',
            subject: 'You\'re invited to join our organization',
            urlTemplate: 'https://yourapp.com/invitations/accept?token={{token}}&email={{email}}',
            sender: 'invites@yourapp.com'
          },
          target: 'invitation'
        }
      },
      {
        mailService: {
          sendMail: async (mailData: types.MailData) => {
            console.log(mailData);
            return true;
          },
        },
        googleOAuthDriver: createGoogleOAuthDriver(
          process.env.GOOGLE_CLIENT_ID!,
          process.env.GOOGLE_CLIENT_SECRET!,
          'https://example.com/auth/oauth/google/callback'
        ),
        twitterOAuthDriver: createTwitterOAuthDriver(
          process.env.TWITTER_CONSUMER_KEY!,
          process.env.TWITTER_CONSUMER_SECRET!,
          'https://example.com/auth/oauth/twitter/callback',
          process.env.SESSION_SECRET!
        ),
        lineOAuthDriver: createLineOAuthDriver(
          process.env.LINE_CHANNEL_ID!,
          process.env.LINE_CHANNEL_SECRET!,
          'https://example.com/auth/oauth/line/callback'
        )
      }
    )
  )
  .use(middlewares.nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 エンドポイント概要​

MethodPath説明
認証エンドポイント
POST/auth/register新しいアイデンティティアカウントを登録
POST/auth/loginアイデンティティを認証し、トークンを受信（MFA有効時はMFAトークンを返す）
POST/auth/mfa/verifyMFAコードを検証し、認証を完了
POST/auth/mfa/resendMFAコードを再送信して検証
POST/auth/ott/loginワンタイムトークン（マジックリンク）を使用して認証
POST/auth/logoutログアウトしてトークンを無効化
メール確認エンドポイント
POST/auth/:identityId/send-verification-emailアイデンティティにメール確認を送信
POST/auth/confirm-email確認トークンでメールを確認
メール管理エンドポイント
PATCH/auth/:identityId/change-emailメール変更プロセスを開始
POST/auth/confirm-new-email新しいメールアドレスを確認
パスワード管理エンドポイント
POST/auth/send-reset-password-link-emailパスワードリセットメールを送信
POST/auth/reset-passwordパスワードリセットプロセスを完了
PATCH/auth/:identityId/change-passwordユーザーパスワードを変更
アカウント管理エンドポイント
POST/auth/activateユーザーアカウントを有効化
POST/auth/deactivateユーザーアカウントを無効化
トークン管理エンドポイント
POST/auth/token/refreshリフレッシュトークンを使用してアクセストークンを更新
POST/auth/token/checkアクセストークンを検証
DELETE/auth/:identityId/refresh-tokensアイデンティティのリフレッシュトークンを削除
招待エンドポイント
POST/invitations新しい招待を作成
GET/invitationsオプションのフィルタリングで招待をリスト
GET/invitations/:invitationIdIDで招待を取得
DELETE/invitations/:invitationId招待を削除
OAuthエンドポイント
GET/auth/oauth/googleGoogle OAuthフローを開始
GET/auth/oauth/google/callbackGoogle OAuthコールバックを処理
GET/auth/oauth/twitterTwitter OAuthフローを開始
GET/auth/oauth/twitter/callbackTwitter OAuthコールバックを処理
GET/auth/oauth/lineLINE OAuthフローを開始
GET/auth/oauth/line/callbackLINE OAuthコールバックを処理

🗄️ エンティティスキーマ​

認証サービスは、次のスキーマでユーザーアイデンティティを管理します：

アイデンティティエンティティ​

{
  "id": "string",
  "email": "string",
  "password": "string",
  "attempts": "number",
  "locked": "boolean",
  "createdAt": "string",
  "updatedAt": "string",
  "typeId": "string",
  "provider": "string",
  "providerId": "string"
}

フィールド詳細​

FieldTypeAuto-GeneratedRequired説明
idstring✅✅一意の識別子（UUID）
emailstring❌⚠️アイデンティティのメールアドレス（一部のOAuthではオプション）
passwordstring❌✅ハッシュ化されたパスワード
attemptsnumber✅✅失敗したログイン試行回数のカウンター
lockedboolean✅✅アカウントロック状態
createdAtstring✅✅作成タイムスタンプ
updatedAtstring✅✅最終更新タイムスタンプ
typeIdstring❌❌アイデンティティのロール識別子（例：「100」は管理者）
providerstring❌⚠️OAuthプロバイダー識別子（例：「google」、「twitter」、「line」）
providerIdstring❌⚠️OAuthアイデンティティ用のプロバイダー固有のユーザーID

追加フィールド詳細:

  • attempts: セキュリティ目的で連続した失敗したログイン試行回数を追跡します。一定の閾値（設定可能）を超えると、アカウントは自動的にロックされます。

  • locked: 失敗したログイン試行が多すぎる、または管理者による操作により、アカウントが現在ロックされているかどうかを示します。ロックされたアカウントは、ロック解除されるまで認証に使用できません。

  • typeId: アイデンティティのロールとシステム内の権限を決定する文字列識別子です。サービスごとに調整可能です。一般的な値には以下が含まれます：

    • "100": システム全体へのアクセス権を持つ管理者
    • "001": 基本的な権限を持つ標準ユーザー
    • "000": 最低限の権限を持つゲストユーザー
    • 必要に応じて追加のカスタムロールを定義できます

  • email: OAuthベースのアイデンティティの場合、すべてのプロバイダーがメールを提供するわけではありません（例：Twitterは常にメールを提供するとは限りません）。標準登録では、メールが必要です。

  • provider: このアイデンティティを作成するために使用されたOAuthプロバイダーを識別します。OAuthベースのアイデンティティに必要です。可能な値：'google'、'twitter'、'line'。

  • providerId: OAuthプロバイダーによってこのユーザーに割り当てられた一意の識別子です。OAuthベースのアイデンティティに必要です。providerと組み合わせて使用し、複数のログインにわたってOAuthアイデンティティを確実に識別および解決します。

招待エンティティ​

認証サービスは、次のスキーマで招待も管理します：

{
  "id": "string",
  "email": "string",
  "fromIdentityId": "string",
  "orgId": "string",
  "role": "string",
  "status": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

招待フィールド詳細​

FieldType自動生成必須説明
idstring✅✅一意の識別子（UUID）
emailstring❌✅招待される人のメールアドレス
fromIdentityIdstring❌✅招待を送信するアイデンティティのID
orgIdstring❌❌招待先の組織のID
rolestring❌❌組織内の招待される人のロール
statusstring❌✅招待ステータス（例：「pending」、「accepted」）
createdAtstring✅✅作成タイムスタンプ
updatedAtstring✅✅最終更新タイムスタンプ

🔐 認証ヘッダー​

保護されたエンドポイントでは、次のヘッダーを含めてください：

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

⚠️ 重要: x-nb-fingerprintヘッダーは、認証時にフィンガープリントが指定された場合、すべての認証済みリクエストで必須です。これがない場合、リクエストは401 Unauthorizedを返します。

🔧 APIエンドポイント​

1. アイデンティティの登録​

メールとパスワードで新しいアイデンティティアカウントを登録します。

リクエスト:

  • Method: POST
  • Path: /auth/register
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
emailstring✅*アイデンティティのメールアドレス
passwordstring✅アイデンティティのパスワード
tokenstring✅*招待トークン

*emailまたはtokenのいずれかが必要ですが、両方は不要です。

レスポンスボディ:

FieldType説明
レスポンスボディなし-登録エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（emailとpassword、またはtokenとpasswordが必要）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

トークン付きリクエスト例（既存ユーザー用）:

curl -X POST {{host}}/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "token": "invitation-token",
    "password": "securepassword123"
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

エラーレスポンス:

メールが既に存在する場合:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "message": "unable to register \"user@example.com\""
  }
}

リクエストボディに必須フィールドがない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'email'",
      "request body must have required property 'token'",
      "request body must match exactly one schema in oneOf"
    ]
  }
}

2. アイデンティティのログイン​

認証情報を認証し、アクセストークンとリフレッシュトークンを受信します。

リクエスト:

  • Method: POST
  • Path: /auth/login
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
emailstring✅アイデンティティのメールアドレス
passwordstring✅アイデンティティのパスワード
fingerprintstring❌セキュリティ用のデバイスフィンガープリント

レスポンスボディ:

FieldType説明
accessTokenstringAPI認証用のJWTアクセストークン
idstringアイデンティティの一意の識別子
refreshTokenstring新しいアクセストークンを取得するためのJWTリフレッシュトークン

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（email、password必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "fingerprint": "device-fingerprint"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Credentials: true
Set-Cookie: accessToken=...; Path=/
Set-Cookie: refreshToken=...; Path=/

{
  "accessToken": "c911c0dd107f8d7e92c0608aa149d041:dee2...",
  "id": "0b3839a6-92b4-4044-a13b-ed834a105646",
  "refreshToken": "9f0cad0da1ceec15c01de729a2359236:2acc8ee1b57fd971473..."
}

エラーレスポンス:

認証情報が無効な場合:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "wrong credentials provided"
  }
}

3. MFAコードの検証​

MFAコードを検証し、MFAが有効な場合に認証を完了します。

リクエスト:

  • Method: POST
  • Path: /auth/mfa/verify
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
tokenstring✅ログインから受信したMFAチャレンジトークン
codestring✅メールで送信されたMFA検証コード

レスポンスボディ:

FieldType説明
accessTokenstringAPI認証用のJWTアクセストークン
idstringアイデンティティの一意の識別子
refreshTokenstring新しいアクセストークンを取得するためのJWTリフレッシュトークン

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（token、code必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "token": "mfa-challenge-token",
    "code": "123456"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Credentials: true
Set-Cookie: accessToken=...; Path=/
Set-Cookie: refreshToken=...; Path=/

{
  "accessToken": "c911c0dd107f8d7e92c0608aa149d041:dee2...",
  "id": "0b3839a6-92b4-4044-a13b-ed834a105646",
  "refreshToken": "9f0cad0da1ceec15c01de729a2359236:2acc8ee1b57fd971473..."
}

エラーレスポンス:

MFAコードが無効な場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid MFA code"
  }
}

トークンが無効または期限切れの場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid or expired MFA token"
  }
}

4. MFAコードの再送信​

ユーザーのメールアドレスにMFA検証コードを再送信します。

リクエスト:

  • Method: POST
  • Path: /auth/mfa/resend
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
tokenstring✅ログインから受信したMFAチャレンジトークン

レスポンスボディ:

FieldType説明
tokenstring新しいMFAチャレンジトークン（以前のトークンは無効化されます）

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（token必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/mfa/resend \
  -H "Content-Type: application/json" \
  -d '{
    "token": "mfa-challenge-token"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "new-mfa-challenge-token"
}

エラーレスポンス:

トークンが無効または期限切れの場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid or expired MFA token"
  }
}

アイデンティティが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

5. アイデンティティのログアウト​

アイデンティティをログアウトし、リフレッシュトークンを無効化します。

リクエスト:

  • Method: POST
  • Path: /auth/logout
  • Headers:
    • Authorization: Bearer <token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要です。Authorizationヘッダーからアクセストークンを使用します。

レスポンスボディ:

FieldType説明
レスポンスボディなし-ログアウトエンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: なし
  • ルートバリデーター: 認証済みリクエストが必要（bearerトークン）

リクエスト例:

curl -X POST {{host}}/auth/logout \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

リフレッシュトークンの無効化操作が失敗した場合:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "failed to delete refresh token"
  }
}

6. ワンタイムトークンでログイン​

ワンタイムトークン（マジックリンク）を使用してユーザーを認証します。

リクエスト:

  • Method: POST
  • Path: /auth/ott/login
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
tokenstring✅認証用のワンタイムトークン

レスポンスボディ:

FieldType説明
accessTokenstringAPI認証用のJWTアクセストークン
idstringアイデンティティの一意の識別子
refreshTokenstring新しいアクセストークンを取得するためのJWTリフレッシュトークン

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（token必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/ott/login \
  -H "Content-Type: application/json" \
  -d '{
    "token": "one-time-token"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Credentials: true
Set-Cookie: accessToken=...; Path=/
Set-Cookie: refreshToken=...; Path=/

{
  "accessToken": "c911c0dd107f8d7e92c0608aa149d041:dee2...",
  "id": "0b3839a6-92b4-4044-a13b-ed834a105646",
  "refreshToken": "9f0cad0da1ceec15c01de729a2359236:2acc8ee1b57fd971473..."
}

エラーレスポンス:

トークンが無効または期限切れの場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid or expired token"
  }
}

7. アクセストークンのリフレッシュ​

有効なリフレッシュトークンを使用してアクセストークンを更新します。

リクエスト:

  • Method: POST
  • Path: /auth/token/refresh
  • Headers:
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
refreshTokenstring✅更新に使用する有効なリフレッシュトークン

レスポンスボディ:

FieldType説明
accessTokenstring新しいアクセストークン
refreshTokenstring新しいリフレッシュトークン

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（refreshToken必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/token/refresh \
  -H "x-nb-fingerprint: <device-fingerprint>" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "<refresh-token>"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

エラーレスポンス:

リフレッシュトークンが無効な場合:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "Invalid refresh token"
  }
}

8. リフレッシュトークンの削除​

特定のアイデンティティのリフレッシュトークンを削除します（管理者のみ、または自分自身）。

リクエスト:

  • Method: DELETE
  • Path: /auth/:identityId/refresh-tokens
  • Headers:
    • Authorization: Bearer <access-token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要
  • パスパラメータ:
    • identityId: リフレッシュトークンを削除するアイデンティティのID

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要

レスポンスボディ:

FieldType説明
レスポンスボディなし-成功時は204 No Contentを返します

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（identityIdパスパラメータ必須）
  • ルートバリデーター: 認証済みリクエストが必要、管理者権限または自己アクセス

リクエスト例（管理者）:

curl -X DELETE {{host}}/auth/user123/refresh-tokens \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

リクエスト例（自己）:

curl -X DELETE {{host}}/auth/current-user-id/refresh-tokens \
  -H "Authorization: Bearer <access-token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

アイデンティティが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

9. 確認メールの送信​

アイデンティティのメールアドレスにメール確認リンクを送信します。

リクエスト:

  • Method: POST
  • Path: /auth/:identityId/send-verification-email
  • Headers:
    • Authorization: Bearer <token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要（管理者または自己アクセス）

パスパラメータ:

FieldType必須説明
identityIdstring✅アイデンティティの一意の識別子

リクエストボディ:

FieldType必須説明
fingerprintstring❌セキュリティ用のデバイスフィンガープリント

レスポンスボディ:

FieldType説明
レスポンスボディなし-確認メール送信エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールまたは自己が必要

リクエスト例:

curl -X POST {{host}}/auth/identity-12345/send-verification-email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "fingerprint": "device-fingerprint"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

メール確認機能が有効になっていない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "verification email feature not enabled"
  }
}

メールサービスがない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "verification email feature requires a mail service to be provided"
  }
}

メール設定がない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "verifyEmailConfig requires emailConfig with fields bodyTemplate, subject, urlTemplate"
  }
}

メール送信が失敗した場合:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to send verification email"
  }
}

10. メールの確認​

確認トークンを使用してアイデンティティのメールアドレスを確認します。

リクエスト:

  • Method: POST
  • Path: /auth/confirm-email
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
tokenstring✅メールからの確認トークン

レスポンスボディ:

FieldType説明
レスポンスボディなし-メール確認エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（token必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/confirm-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "jwt-verification-token"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

トークンが無効な場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Unable to verify token"
  }
}

11. 招待の作成​

エンティティがサービスに参加するための新しい招待を作成します。

リクエスト:

  • Method: POST
  • Path: /invitations
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要（管理者アクセス）

リクエストボディ:

FieldType必須説明
emailstring✅招待される人のメールアドレス
fromIdentityIdstring✅招待を送信するアイデンティティのID
orgIdstring❌招待先の組織のID
rolestring❌組織内の招待される人のロール

レスポンスボディ:

FieldType説明
invitationIdstring作成された招待の一意の識別子

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（email、fromIdentityId必須；追加プロパティは許可されません）
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールが必要

リクエスト例:

curl -X POST {{host}}/invitations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "email": "newuser@example.com",
    "fromIdentityId": "392157b1-dc7a-4935-a6f9-a2d333b910ea"
    "orgId": "org123",
    "role": "member"
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "invitationId": "62564a60-e720-4907-bb85-3afaa2729e0d"
}

エラーレスポンス:

リクエストボディに必須フィールドがない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'email'"
    ]
  }
}

リクエストボディにfromIdentityIdがない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'fromIdentityId'"
    ]
  }
}

メール形式が無効な場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must match format \"email\""
    ]
  }
}

リクエストに追加プロパティが含まれている場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties"
    ]
  }
}

招待の作成が失敗した場合:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to create invitation"
  }
}

12. 招待のリスト取得​

オプションのフィルタリングとページネーションですべての招待を取得します。

リクエスト:

  • Method: GET
  • Path: /invitations
  • Headers:
    • Authorization: Bearer <token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要（管理者アクセス）

クエリパラメータ:

FieldType必須説明
emailstring❌招待される人のメールアドレスでフィルタ
fromIdentityIdstring❌招待者アイデンティティIDでフィルタ
orgIdstring❌組織IDでフィルタ
rolestring❌ロールでフィルタ
pagenumber❌ページネーションのページ番号（1-1000）
limitnumber❌ページあたりの項目数（1-50）

レスポンスボディ: ページネーション付き招待リストとメタデータを含むJSON

レスポンス構造:

FieldType説明
dataarray招待オブジェクトの配列
data[].emailstring招待される人のメールアドレス
data[].fromIdentityIdstring招待を送信するアイデンティティのID
data[].orgIdstring招待先の組織のID
data[].rolestring組織内の招待される人のロール
data[].statusstring招待ステータス（例：「pending」、「accepted」）
data[].createdAtstring作成タイムスタンプ
data[].idstring一意の招待識別子
data[].updatedAtstring最終更新タイムスタンプ
metadata.paginationobjectページネーション情報
metadata.pagination.pagenumber現在のページ番号
metadata.pagination.limitnumberページあたりの項目数
metadata.pagination.totalnumber招待の総数
metadata.pagination.totalPagesnumber総ページ数
metadata.pagination.hasNextboolean次のページがあるかどうか
metadata.pagination.hasPrevboolean前のページがあるかどうか

バリデーション:

  • スキーマバリデーション: 自動的に強制されます
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールが必要

リクエスト例:

curl -X GET "{{host}}/invitations" \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "email": "newuser@example.com",
      "fromIdentityId": "392157b1-dc7a-4935-a6f9-a2d333b910ea",
      "orgId": "org123",
      "role": "member",
      "status": "pending",
      "createdAt": "2025-07-04T06:29:32.905Z",
      "id": "62564a60-e720-4907-bb85-3afaa2729e0d",
      "updatedAt": "2025-07-04T06:29:32.905Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

空のレスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 0,
      "totalPages": 0,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

13. IDで招待を取得​

一意の識別子で特定の招待を取得します。

リクエスト:

  • Method: GET
  • Path: /invitations/:invitationId
  • Headers:
    • Authorization: Bearer <token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要（管理者アクセス）

パスパラメータ:

FieldType必須説明
invitationIdstring✅一意の招待識別子

バリデーション:

  • スキーマバリデーション: 自動的に強制されます
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールが必要

リクエスト例:

curl -X GET {{host}}/invitations/62564a60-e720-4907-bb85-3afaa2729e0d \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "email": "newuser@example.com",
    "fromIdentityId": "392157b1-dc7a-4935-a6f9-a2d333b910ea",
    "orgId": "org123",
    "role": "member",
    "status": "pending",
    "createdAt": "2025-07-04T06:29:32.905Z",
    "id": "62564a60-e720-4907-bb85-3afaa2729e0d",
    "updatedAt": "2025-07-04T06:29:32.905Z"
  }

エラーレスポンス:

招待が見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Invitation not found"
  }
}

14. 招待の削除​

一意の識別子で特定の招待を削除します。

リクエスト:

  • Method: DELETE
  • Path: /invitations/:invitationId
  • Headers:
    • Authorization: Bearer <token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要（管理者アクセス）

パスパラメータ:

FieldType必須説明
invitationIdstring✅一意の招待識別子

バリデーション:

  • スキーマバリデーション: 自動的に強制されます
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールが必要

リクエスト例:

curl -X DELETE {{host}}/invitations/62564a60-e720-4907-bb85-3afaa2729e0d \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

招待が見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Invitation not found"
  }
}

15. メールアドレスの変更​

新しいメールアドレスに確認メールを送信して、ユーザーのメール変更プロセスを開始します。

リクエスト:

  • Method: PATCH
  • Path: /auth/:identityId/change-email
  • Headers:
    • Content-Type: application/json
  • Authorization: Bearerトークンが必要（管理者または自己アクセス）

パスパラメータ:

FieldType必須説明
identityIdstring✅アイデンティティの一意の識別子

リクエストボディ:

FieldType必須説明
emailstring✅アイデンティティの新しいメールアドレス

レスポンスボディ:

FieldType説明
レスポンスボディなし-メール変更エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（email必須、有効なメール形式である必要があります）
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールまたは自己が必要

リクエスト例:

curl -X PATCH {{host}}/auth/identity-12345/change-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newemail@example.com"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

メールが既に存在する場合:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "message": "Email already exists"
  }
}

アイデンティティが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

16. 新しいメールアドレスの確認​

ワンタイム確認トークンを使用してユーザーの新しいメールアドレスを確認します。

リクエスト:

  • Method: POST
  • Path: /auth/confirm-new-email
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
tokenstring✅メールからの確認トークン

レスポンスボディ:

FieldType説明
レスポンスボディなし-新しいメール確認エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（token必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/confirm-new-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "jwt-verification-token"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

トークンが無効な場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid token"
  }
}

17. パスワードリセットリンクメールの送信​

ユーザーのメールアドレスに基づいてパスワードリセットリンクメールを送信します。

リクエスト:

  • Method: POST
  • Path: /auth/send-reset-password-link-email
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
emailstring✅パスワードリセット用のメールアドレス

レスポンスボディ:

FieldType説明
レスポンスボディなし-パスワードリセットリンクメール送信エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（email必須、有効なメール形式である必要があります）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/send-reset-password-link-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

メールが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Email not found"
  }
}

18. パスワードリセットの完了​

トークンを検証し、ユーザーのパスワードを更新してパスワードリセットプロセスを完了します。

リクエスト:

  • Method: POST
  • Path: /auth/reset-password
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <one-time-token>
  • Authorization: Bearerトークンが必要（ワンタイムトークン）

リクエストボディ:

FieldType必須説明
passwordstring✅新しいパスワード（8-24文字、小文字と数字を含む必要があります）

レスポンスボディ:

FieldType説明
レスポンスボディなし-パスワードリセット完了エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（password必須、セキュリティ要件を満たす必要があります）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/reset-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <one-time-token>" \
  -d '{
    "password": "newSecurePassword123"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

トークンが無効な場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid token"
  }
}

パスワードが要件を満たさない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "password must match pattern \"^(?=.*[a-z])(?=.*\\d)[a-zA-Z0-9?/_-]{8,24}$\""
    ]
  }
}

19. パスワードの変更​

PATCH /auth/:identityId/change-password を使用してユーザーパスワードを変更します。

リクエスト:

  • Method: PATCH
  • Path: /auth/:identityId/change-password
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
    • x-nb-fingerprint: <device-fingerprint>
  • Authorization: Bearerトークンが必要

パスパラメータ:

FieldType必須説明
identityIdstring✅アイデンティティの一意の識別子

リクエストボディ:

FieldType必須説明
passwordstring✅確認用の現在のパスワード
newPasswordstring✅新しいパスワード（8-24文字、小文字と数字を含む必要があります）

レスポンスボディ:

FieldType説明
レスポンスボディなし-パスワード変更エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（password、newPassword必須、newPasswordはセキュリティ要件を満たす必要があります）
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールまたは自己が必要

リクエスト例:

curl -X PATCH {{host}}/auth/identity-12345/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "password": "oldPassword123",
    "newPassword": "newSecurePassword123"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

現在のパスワードが正しくない場合:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "Current password is incorrect"
  }
}

新しいパスワードが要件を満たさない場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "newPassword must match pattern \"^(?=.*[a-z])(?=.*\\d)[a-zA-Z0-9?/_-]{8,24}$\""
    ]
  }
}

20. アカウントの有効化​

POST /auth/activate を使用してユーザーアカウントを有効化します。

リクエスト:

  • Method: POST
  • Path: /auth/activate
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトークンが必要（管理者アクセス）

リクエストボディ:

FieldType必須説明
identityIdstring✅有効化するアイデンティティの一意の識別子

レスポンスボディ:

FieldType説明
レスポンスボディなし-アカウント有効化エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（identityId必須）
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールが必要

リクエスト例:

curl -X POST {{host}}/auth/activate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "identityId": "identity-12345"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

アイデンティティが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

メールが確認されていない場合:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Email must be verified before activation"
  }
}

21. アカウントの無効化​

POST /auth/deactivate を使用してユーザーアイデンティティを無効化します。

リクエスト:

  • Method: POST
  • Path: /auth/deactivate
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトークンが必要（管理者または自己アクセス）

リクエストボディ:

FieldType必須説明
identityIdstring✅無効化するアイデンティティの一意の識別子

レスポンスボディ:

FieldType説明
レスポンスボディなし-アカウント無効化エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（identityId必須）
  • ルートバリデーター:
    • 認証済みリクエストが必要（bearerトークン）
    • 管理者ロールまたは自己が必要

リクエスト例:

curl -X POST {{host}}/auth/deactivate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "identityId": "identity-12345"
  }'

成功レスポンス:

HTTP/1.1 204 No Content
Content-Type: application/json

エラーレスポンス:

アイデンティティが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

メールが確認されていない場合:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Email must be verified before deactivation"
  }
}

トークンが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Missing token header"
  }
}

メール送信が失敗した場合:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to send email"
  }
}

22. トークンの確認​

アクセストークンを検証し、そのステータスを返します。

リクエスト:

  • Method: POST
  • Path: /auth/token/check
  • Headers:
    • Content-Type: application/json
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
tokenstring✅検証するトークン
targetstring❌検証用のオプションのターゲットコンテキスト

レスポンスボディ:

FieldType説明
identityIdstringトークンが有効な場合のアイデンティティID

バリデーション:

  • スキーマバリデーション: 自動的に強制されます（token必須）
  • ルートバリデーター: なし

リクエスト例:

curl -X POST {{host}}/auth/token/check \
  -H "Content-Type: application/json" \
  -d '{
    "token": "jwt-token-to-validate",
    "target": "optional-target-context"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "identityId": "811ff0a3-a26f-447b-b68a-dd83ea4000b9"
}

エラーレスポンス:

トークンが無効な場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Unable to verify token"
  }
}

23. Google OAuthの開始​

ユーザーをGoogleの認証ページにリダイレクトして、Google OAuth認証フローを開始します。このフローはユーザーのログインとサインアップの両方に使用でき、初回ユーザーのアカウントを自動的に作成するか、既存ユーザーを認証します。

リクエスト:

  • Method: GET
  • Path: /auth/oauth/google
  • Headers: 不要
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要。設定にはクエリパラメータを使用します。

クエリパラメータ:

FieldType必須説明
fpstring✅セキュリティ用のデバイスフィンガープリント
purposestring✅OAuthの目的: oauth-login または oauth-signup
redirectUrlstring✅OAuth完了後にリダイレクトするURL
typeIdstring❌アイデンティティタイプID（サインアップ時は必須）

レスポンス:

  • Status: 302 Found
  • Headers: Google OAuth URLを含む Location ヘッダー

レスポンスボディ:

FieldType説明
レスポンスボディなし-OAuth開始エンドポイントは成功時にレスポンスボディを返しません

リクエスト例:

# OAuth Login
curl -v "{{host}}/auth/oauth/google?fp=device-fingerprint&purpose=oauth-login&redirectUrl=http://localhost/oauth/callback"

# OAuth Signup
curl -v "{{host}}/auth/oauth/google?fp=device-fingerprint&purpose=oauth-signup&redirectUrl=http://localhost/oauth/callback&typeId=001"

成功レスポンス:

HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?prompt=consent&response_type=code&redirect_uri=...&scope=email%20profile&state=...&client_id=...

エラーレスポンス:

必須パラメータが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "query parameter 'fp' is required",
      "query parameter 'purpose' is required",
      "query parameter 'redirectUrl' is required"
    ]
  }
}

purposeの値が無効な場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "query parameter 'purpose' must be equal to one of the allowed values"
    ]
  }
}

24. Google OAuthコールバック​

Google OAuthコールバックを処理し、認証フローを完了します。処理が成功した後、ユーザーは初期OAuthリクエストで指定された redirectUrl に、認証トークン（ワンタイムトークンまたはアクセストークン）と共にリダイレクトされます。

リクエスト:

  • Method: GET
  • Path: /auth/oauth/google/callback
  • Headers: 不要
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要。OAuthコールバック処理にはクエリパラメータを使用します。

クエリパラメータ:

FieldType必須説明
codestring✅Googleからのワンタイム認証コード（Passport.jsがトークン交換のために使用）
statestring✅OAuthフローコンテキスト（purpose、redirectUrl、typeId、fingerprint、userAgent）を含む署名付きJWT

レスポンス:

  • Status: 302 Found（最終的な宛先にリダイレクト）
  • Headers: 最終リダイレクトURLを含む Location ヘッダー

レスポンスボディ:

FieldType説明
レスポンスボディなし-OAuthコールバックエンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: なし
  • ルートバリデーター: なし

リクエスト例:

curl -v "{{host}}/auth/oauth/google/callback?code=AUTH_CODE&state=STATE_TOKEN"

成功レスポンス:

HTTP/1.1 302 Found
Location: http://localhost:3000/oauth/callback?token=JWT_TOKEN

エラーレスポンス:

OAuth stateが無効または期限切れの場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid onetime token"
  }
}

サインアップ時にtypeIdが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "typeId is required"
  }
}

アイデンティティの作成が失敗した場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Failed to create identity"
  }
}

アイデンティティが見つからない場合（ログインのみ）:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "No identity found for the given google account."
  }
}

メールが既に存在する場合（サインアップのみ）:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "message": "Email already in use"
  }
}

データベース操作が失敗した場合:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Error finding or creating identity"
  }
}

25. Twitter OAuthの開始​

ユーザーをTwitterの認証ページにリダイレクトして、Twitter OAuth認証フローを開始します。このフローはユーザーのログインとサインアップの両方に使用でき、初回ユーザーのアカウントを自動的に作成するか、既存ユーザーを認証します。

リクエスト:

  • Method: GET
  • Path: /auth/oauth/twitter
  • Headers: 不要
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要。設定にはクエリパラメータを使用します。

クエリパラメータ:

FieldType必須説明
purposestring✅OAuthの目的: oauth-login または oauth-signup
redirectUrlstring✅OAuth完了後にリダイレクトするURL
typeIdstring❌アイデンティティタイプID（サインアップ時は必須）

レスポンス:

  • Status: 302 Found
  • Headers: Twitter OAuth URLを含む Location ヘッダー

レスポンスボディ:

FieldType説明
レスポンスボディなし-OAuth開始エンドポイントは成功時にレスポンスボディを返しません

リクエスト例:

# OAuth Login
curl -v "{{host}}/auth/oauth/twitter?fp=device-fingerprint&purpose=oauth-login&redirectUrl=http://localhost/oauth/callback"

# OAuth Signup
curl -v "{{host}}/auth/oauth/twitter?fp=device-fingerprint&purpose=oauth-signup&redirectUrl=http://localhost/oauth/callback&typeId=001"

成功レスポンス:

HTTP/1.1 302 Found
Location: https://api.twitter.com/oauth/authenticate?oauth_token=...

エラーレスポンス:

必須パラメータが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "query parameter 'fp' is required",
      "query parameter 'purpose' is required",
      "query parameter 'redirectUrl' is required"
    ]
  }
}

26. Twitter OAuthコールバック​

Twitter OAuthコールバックを処理し、認証フローを完了します。処理が成功した後、ユーザーは初期OAuthリクエストで指定された redirectUrl に、認証トークンと共にリダイレクトされます。

リクエスト:

  • Method: GET
  • Path: /auth/oauth/twitter/callback
  • Headers: 不要
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要。OAuthコールバック処理にはクエリパラメータを使用します。

クエリパラメータ:

FieldType必須説明
oauth_tokenstring✅TwitterからのOAuthトークン
oauth_verifierstring✅TwitterからのOAuth verifier

レスポンス:

  • Status: 302 Found（最終的な宛先にリダイレクト）
  • Headers: 最終リダイレクトURLを含む Location ヘッダー

レスポンスボディ:

FieldType説明
レスポンスボディなし-OAuthコールバックエンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: なし
  • ルートバリデーター: なし

リクエスト例:

curl -v "{{host}}/auth/oauth/twitter/callback?oauth_token=OAUTH_TOKEN&oauth_verifier=OAUTH_VERIFIER"

成功レスポンス:

HTTP/1.1 302 Found
Location: http://localhost:3000/oauth/callback?token=JWT_TOKEN

エラーレスポンス:

OAuthトークンが無効または期限切れの場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid OAuth token"
  }
}

サインアップ時にtypeIdが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "typeId is required"
  }
}

アイデンティティの作成が失敗した場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Failed to create identity"
  }
}

アイデンティティが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "No identity found for the given twitter account."
  }
}

27. LINE OAuthの開始​

ユーザーをLINEの認証ページにリダイレクトして、LINE OAuth認証フローを開始します。このフローはユーザーのログインとサインアップの両方に使用でき、初回ユーザーのアカウントを自動的に作成するか、既存ユーザーを認証します。

リクエスト:

  • Method: GET
  • Path: /auth/oauth/line
  • Headers: 不要
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要。OAuth開始にはクエリパラメータを使用します。

クエリパラメータ:

FieldType必須説明
fpstring✅セキュリティ用のデバイスフィンガープリント
purposestring✅OAuthの目的: oauth-login または oauth-signup
redirectUrlstring✅認証後にリダイレクトするURL
typeIdstring❌新規ユーザー用のアイデンティティタイプ識別子（サインアップ時は必須）

レスポンス:

  • Status: 302 Found（LINE認証ページにリダイレクト）
  • Headers: LINE OAuth URLを含む Location ヘッダー

レスポンスボディ:

FieldType説明
レスポンスボディなし-OAuth開始エンドポイントはLINE認証ページにリダイレクトします

バリデーション:

  • スキーマバリデーション: なし
  • ルートバリデーター: なし

リクエスト例:

curl -X GET "{{host}}/auth/oauth/line?fp=device-fingerprint&purpose=oauth-signup&redirectUrl=https://example.com/auth/callback&typeId=regular"

成功レスポンス:

HTTP/1.1 302 Found
Location: https://access.line.me/oauth2/v2.1/authorize?...

エラーレスポンス:

redirectUrlが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "redirectUrl is required"
  }
}

typeIdが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "typeId is required"
  }
}

28. LINE OAuthコールバック​

LINE OAuthコールバックを処理し、認証フローを完了します。処理が成功した後、ユーザーは初期OAuthリクエストで指定された redirectUrl に、認証トークンと共にリダイレクトされます。

リクエスト:

  • Method: GET
  • Path: /auth/oauth/line/callback
  • Headers: 不要
  • Authorization: 不要

リクエストボディ:

FieldType必須説明
リクエストボディなし-ボディは不要。OAuthコールバック処理にはクエリパラメータを使用します。

クエリパラメータ:

FieldType必須説明
codestring✅LINEからの認証コード
statestring✅CSRF保護用のstateパラメータ

レスポンス:

  • Status: 302 Found（最終的な宛先にリダイレクト）
  • Headers: 最終リダイレクトURLを含む Location ヘッダー

レスポンスボディ:

FieldType説明
レスポンスボディなし-OAuthコールバックエンドポイントは成功時にレスポンスボディを返しません

バリデーション:

  • スキーマバリデーション: なし
  • ルートバリデーター: なし

リクエスト例:

# Automatically called by LINE after authorization:
GET {{host}}/auth/oauth/line/callback?code=AUTHORIZATION_CODE&state=STATE_STRING

成功レスポンス:

HTTP/1.1 302 Found
Location: https://example.com/auth/callback?token=ACCESS_TOKEN

エラーレスポンス:

LINE認証が失敗した場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "LINE authorization failed"
  }
}

typeIdが欠落している場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "typeId is required"
  }
}

アイデンティティの作成が失敗した場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Identity creation failed"
  }
}

アイデンティティが見つからない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "No identity found for the given LINE account."
  }
}

🔒 セキュリティ機能​

アカウント保護​

  • 失敗したログイン試行: 失敗したログイン試行を追跡
  • アカウントロック: 5回の失敗試行後にアカウントを自動的にロック（設定可能）
  • パスワードハッシュ化: パスワードは安全にハッシュ化されます
  • トークンセキュリティ: JWTトークンにはデバイスフィンガープリントとIP検証が含まれます

トークン管理​

  • アクセストークン: APIアクセス用の短命トークン
  • リフレッシュトークン: トークン更新用の長命トークン
  • トークン検証: ドメイン、フィンガープリント、IP、ユーザーエージェントを検証
  • セキュアCookie: トークン保存用のHTTP-onlyセキュアCookie

認証方法​

Bearerトークン認証​

// Authorizationヘッダーで使用
Authorization: Bearer <access-token>

Cookie認証​

// リクエストと共にトークンが自動的に送信されます

⚙️ 設定オプション​

サービス設定​

interface AuthenticationServiceConfiguration {
  authSecrets: {
    authEncSecret: string;    // JWT暗号化シークレット
    authSignSecret: string;   // JWT署名シークレット
  };
  maxFailedLoginAttempts?: number;  // デフォルト: 5
  isMfaEnabled?: boolean;           // 多要素認証を有効化（デフォルト: false）
  mfaCodeLength?: number;           // MFAコードの長さ（デフォルト: 6）
  mfaTokenExpireTime?: string;      // MFAトークンの有効期限（デフォルト: '10m')
  cookieOpts?: {
    domain?: string;
    maxAge?: string | number;
    path?: string;
    sameSite?: 'strict' | 'lax' | 'none';
  };
  jwtOpts?: {
    jwtSignOptions?: SignOptions;
    stateful?: boolean;
  };
  accessTokenExpireTime?: string;    // デフォルト: '2h'
  onetimeTokenExpireTime?: string;   // デフォルト: '48h'
  refreshTokenExpireTime?: string;   // デフォルト: '2d'
  identity?: {
    typeIds?: {
      admin: string;          // 管理者ユーザータイプ識別子
      guest: string;          // ゲストユーザータイプ識別子
      regular: string;        // 通常ユーザータイプ識別子
    };
  };
  mfaCodeEmailConfig?: {             // isMfaEnabledがtrueの場合必須
    sender: string;                  // 送信者メールアドレス
    emailConfig: {
      subject: string;               // メール件名
      bodyTemplate: string;          // ${code}プレースホルダーを含むメール本文テンプレート
    };
  };
  verifyEmailConfig?: {
    enabled: boolean;                // メール確認機能を有効化
    emailConfig?: {
      bodyTemplate: string;          // {{email}}と{{token}}プレースホルダーを含むメール本文テンプレート
      subject: string;               // メール件名
      urlTemplate: string;           // {{token}}プレースホルダーを含むURLテンプレート
    };
    sender?: string;                 // 送信者メールアドレス
  };
  sendResetPasswordEmailConfig?: {
    emailConfig: {
      bodyTemplate: string;          // パスワードリセット用のメール本文テンプレート
      subject: string;               // パスワードリセット用のメール件名
      urlTemplate: string;           // {{token}}プレースホルダーを含むURLテンプレート
    };
    sender: string;                  // パスワードリセットメールの送信者メールアドレス
  };
  resetPasswordSuccessConfig?: {
    emailConfig: {
      bodyTemplate: string;          // パスワードリセット成功用のメール本文テンプレート
      subject: string;               // パスワードリセット成功用のメール件名
      urlTemplate: string;           // 成功確認用のURLテンプレート
    };
    sender: string;                  // 成功通知用の送信者メールアドレス
  };
  changePasswordConfig?: {
    emailConfig: {
      bodyTemplate: string;          // パスワード変更通知用のメール本文テンプレート
      subject: string;               // パスワード変更用のメール件名
      urlTemplate: string;           // 変更確認用のURLテンプレート
    };
    sender: string;                  // パスワード変更通知用の送信者メールアドレス
  };
  deactivateIdentityEmailConfig?: {
    emailConfig: {
      bodyTemplate: string;          // アカウント無効化用のメール本文テンプレート
      subject: string;               // 無効化用のメール件名
      urlTemplate: string;           // 無効化確認用のURLテンプレート
    };
    sender: string;                  // 無効化メールの送信者メールアドレス
  };
  invitation?: {
    enabled: boolean;                // 招待機能を有効化
    emailConfig?: {
      bodyTemplate: string;          // {{email}}と{{token}}プレースホルダーを含むメール本文テンプレート
      subject: string;               // メール件名
      urlTemplate: string;           // {{token}}プレースホルダーを含むURLテンプレート
      sender: string;                // 送信者メールアドレス
    };
    target?: string;                 // 招待検証用のトークンターゲット
    status?: {
      pending?: string;              // 保留中の招待のステータス識別子
      accepted?: string;             // 承認済み招待のステータス識別子
    };
  };
}

設定の詳細​

認証サービスの設定は、セキュリティ、Cookie、JWT設定、招待、メール確認の論理的なグループに整理されています。

🔐 セキュリティ設定​

authSecrets - JWTトークンのセキュリティシークレット

  • Type: { authEncSecret: string; authSignSecret: string }
  • Description: JWTの暗号化と署名用のシークレットキー
  • Default: { authEncSecret: '', authSignSecret: '' }
  • Required: はい（本番環境では必須）
  • Child Properties:
    • authEncSecret: JWTペイロード暗号化用のシークレットキー
    • authSignSecret: JWT署名検証用のシークレットキー

maxFailedLoginAttempts - アカウントロックアウトの閾値

  • Type: number
  • Description: アカウントロックアウトまでの最大失敗ログイン試行回数
  • Default: 5
  • Behavior: 閾値を超えるとアカウントをロックし、手動でのロック解除が必要

🔐 多要素認証（MFA）設定​

isMfaEnabled - ログイン時のMFAを有効化

  • Type: boolean
  • Description: ユーザーログイン時の多要素認証を有効化します
  • Default: false
  • Behavior: 有効にすると、認証情報の検証後にメールで送信されたコードを確認する必要があります
  • Requirements: mfaCodeEmailConfigの設定が必要です
  • Use Case: 機密性の高いアプリケーションのセキュリティ強化

mfaCodeLength - MFA検証コードの長さ

  • Type: number
  • Description: 生成されるMFAコードの桁数
  • Default: 6
  • Format: 先頭にゼロを含む数値文字列（例: "012345"）
  • Security: 長いコードはセキュリティが向上しますが、ユーザーフレンドリーさは低下します

mfaTokenExpireTime - MFAチャレンジトークンの有効期限

  • Type: string (msパッケージ形式)
  • Description: ユーザーがMFAコードを送信できる時間枠
  • Default: '10m' (10分)
  • Format: msパッケージ形式 ('5m', '10m', '15m')
  • Security: 短い有効期限は攻撃の時間枠を減らします
  • UX: 長い有効期限はユーザー体験を向上させます

mfaCodeEmailConfig - MFAコードメール設定

  • Type: { sender: string; emailConfig: { subject: string; bodyTemplate: string } }
  • Description: MFAコード配信用のメール設定
  • Required: はい、isMfaEnabledがtrueの場合
  • Child Properties:
    • sender: 送信者メールアドレス
      • Type: string
      • Description: MFAコードメールの送信者として表示されるメールアドレス
      • Example: 'noreply@example.com'
    • emailConfig: メールテンプレート設定
      • Type: { subject: string; bodyTemplate: string }
      • Child Properties:
        • subject: メール件名
          • Type: string
          • Example: 'Your MFA Code'
        • bodyTemplate: メール本文テンプレート
          • Type: string
          • Description: MFAコード用の${code}プレースホルダーを含むHTML/テキストテンプレート
          • Example: 'Your verification code is: ${code}'

MFAフロー:

  1. ユーザーが /auth/login 経由で認証情報を送信
  2. システムが認証情報を検証
  3. MFAが有効な場合:
    • セキュアな数値MFAコードを生成
    • 時間制限付きMFAチャレンジトークンを作成
    • メールでコードを送信
    • MFAトークンをクライアントに返す
    • クライアントは /auth/mfa/verify エンドポイントにトークンとコードを送信する必要があります
    • システムがコードを検証し、アクセス/リフレッシュトークンを返す
  4. MFAが無効な場合:
    • アクセス/リフレッシュトークンを即座に生成して返す

🍪 Cookie設定​

cookieOpts - HTTP Cookie設定

  • Type: { domain?: string; maxAge?: string | number; path?: string; sameSite?: 'strict' | 'lax' | 'none' }
  • Description: 認証トークンをブラウザのCookieに保存する方法を制御します
  • Default: undefined (トークンの有効期限を使用)
  • Child Properties:
    • domain: Cookieのドメインスコープ
      • Type: string
      • Description: サブドメイン間でのCookieスコープを制御します
      • Example: '.example.com' ですべてのサブドメインに適用
    • maxAge: Cookieの有効期限
      • Type: string | number
      • Description: Cookieの有効期限をミリ秒で設定します
    • path: Cookieのパススコープ
      • Type: string
      • Description: Cookieを特定のURLパスに制限します
      • Default: '/' (ドメイン全体)
      • Example: '/api' でAPI専用のCookie
    • sameSite: CSRF保護レベル
      • Type: 'strict' | 'lax' | 'none'
      • Description: クロスサイトリクエストでCookieが送信されるタイミングを制御します
      • Values:
        • 'strict': 同一サイトリクエストでのみCookieを送信（最も安全）
        • 'lax': クロスサイトナビゲーションでCookieを送信（バランス型）
        • 'none': すべてのクロスサイトリクエストでCookieを送信（secure: trueが必要）

🔑 JWT設定​

jwtOpts - JWTトークン生成と検証オプション

  • Type: { jwtSignOptions?: SignOptions; stateful?: boolean }
  • Description: JWT署名と検証の動作をカスタマイズします
  • Default: undefined (標準のJWT設定を使用)
  • Child Properties:
    • jwtSignOptions: JWT署名設定
      • Type: SignOptions (jsonwebtokenパッケージから)
      • Description: JWT署名アルゴリズムとパラメータをカスタマイズします
      • Default: 標準のJWT署名
    • stateful: サーバーサイドトークン検証（このプロパティは確認が必要です）
      • Type: boolean
      • Description: セキュリティ強化のためサーバーサイドトークン検証を有効化します
      • Default: false (ステートレス)
      • Use Case: トークンの取り消しとセキュリティ強化

⏰ トークン有効期限​

accessTokenExpireTime - アクセストークンの有効期限

  • Type: string (msパッケージ形式)
  • Description: APIアクセス用の短命トークン
  • Default: undefined
  • Format: msパッケージ形式 ('30m', '1h', '2h')
  • Security: 露出時間を最小化します

refreshTokenExpireTime - リフレッシュトークンの有効期限

  • Type: string (msパッケージ形式)
  • Description: 新しいアクセストークンを取得するための長命トークン
  • Default: undefined
  • Format: msパッケージ形式 ('1d', '7d', '30d')
  • Security: セキュアなHTTP-only Cookieに保存されます

onetimeTokenExpireTime - ワンタイムトークンの有効期限

  • Type: string (msパッケージ形式)
  • Description: パスワードリセット、メール確認用の一時トークン
  • Default: undefined
  • Format: msパッケージ形式 ('15m', '1h', '2h')
  • Security: 短い有効期限の使い捨てトークン

📧 メール確認設定​

verifyEmailConfig - メール確認設定

  • Type: { enabled: boolean; emailConfig?: EmailConfig; mailService?: MailService; sender: string }
  • Description: メール確認機能とメールテンプレートを制御します
  • Default: undefined (メール確認は無効)
  • Child Properties:
    • enabled: メール確認機能を有効化
      • Type: boolean
      • Description: メール確認機能のマスタースイッチ
      • Default: false
      • Required: はい（メール確認を使用する場合）
    • emailConfig: メールテンプレート設定
      • Type: { bodyTemplate: string; subject: string; urlTemplate: string }
      • Description: 確認メール用のテンプレート
      • Required: はい（有効な場合）
      • Child Properties:
        • bodyTemplate: HTMLメール本文テンプレート
          • Type: string
          • Description: {{url}}、{{email}}、{{token}}プレースホルダーを含むメール本文用のHTMLテンプレート。urlにはurlTemplateの値が使用されます
          • Example: "Hello {{email}}, click <a href="{{url}}">here</a> to verify your email."
        • subject: メール件名
          • Type: string
          • Description: 確認メールの件名
          • Example: "Verify your email address"
        • urlTemplate: 確認リンク用のURLテンプレート
          • Type: string
          • Description: {{email}}と{{token}}プレースホルダーを含むURLテンプレート
          • Example: "https://yourapp.com/verify?token={{token}}"
    • sender: 送信者メールアドレス
      • Type: string
      • Description: 確認メールの送信元メールアドレス
      • Required: いいえ（オプション）
      • Example: "noreply@yourapp.com"

🔐 パスワードリセットメール設定​

sendResetPasswordEmailConfig - パスワードリセットメール設定

  • Type: { emailConfig: EmailConfig; sender: string }
  • Description: パスワードリセットメールテンプレートと送信者を制御します
  • Default: bodyTemplate: 'Reset your password by clicking ${url}'の事前定義テンプレート
  • Child Properties:
    • emailConfig: メールテンプレート設定
      • Type: { bodyTemplate: string; subject: string; urlTemplate: string }
      • Description: パスワードリセットメール用のテンプレート
      • Required: はい
      • Child Properties:
        • bodyTemplate: メール本文テンプレート
          • Type: string
          • Description: ${url}プレースホルダーを含むHTMLテンプレート
          • Example: 'Reset your password by clicking ${url}'
        • subject: メール件名
          • Type: string
          • Description: パスワードリセットメールの件名
          • Example: 'Reset your password'
        • urlTemplate: URLテンプレート
          • Type: string
          • Description: ${token}プレースホルダーを含むURLテンプレート
          • Example: 'https://yourapp.com/reset-password?token=${token}'
    • sender: 送信者メールアドレス
      • Type: string
      • Description: パスワードリセットメールの送信元メールアドレス
      • Required: はい
      • Example: "noreply@yourapp.com"

resetPasswordSuccessConfig - パスワードリセット成功メール設定

  • Type: { emailConfig: EmailConfig; sender: string }
  • Description: パスワードリセット成功通知テンプレートを制御します
  • Default: bodyTemplate: 'Your password has been reset'の事前定義テンプレート
  • Child Properties:
    • emailConfig: メールテンプレート設定（上記と同じ構造）
    • sender: 成功通知用の送信者メールアドレス

changePasswordConfig - パスワード変更通知設定

  • Type: { emailConfig: EmailConfig; sender: string }
  • Description: パスワード変更通知テンプレートを制御します
  • Default: bodyTemplate: 'Your password has been changed'の事前定義テンプレート
  • Child Properties:
    • emailConfig: メールテンプレート設定（上記と同じ構造）
    • sender: パスワード変更通知用の送信者メールアドレス

deactivateIdentityEmailConfig - アカウント無効化メール設定

  • Type: { emailConfig: EmailConfig; sender: string }
  • Description: アカウント無効化通知テンプレートを制御します
  • Default: bodyTemplate: 'Your account has been deactivated'の事前定義テンプレート
  • Child Properties:
    • emailConfig: メールテンプレート設定（上記と同じ構造）
    • sender: 無効化通知用の送信者メールアドレス

サービスオプション（第3引数）​

interface AuthServiceOptions {
  mailService?: MailService;        // メールサービス実装
  fileStorageDriver?: FileStorageDriver; // ファイル操作用のファイルストレージドライバー
  googleOAuthDriver?: GoogleOAuthDriver; // Google OAuthドライバーインスタンス
  twitterOAuthDriver?: TwitterOAuthDriver; // Twitter OAuthドライバーインスタンス
  lineOAuthDriver?: LineOAuthDriver; // LINE OAuthドライバーインスタンス
}

これらは authService(dataStores, config, options) の第3引数として提供します。

📨 招待設定​

invitation - 招待管理設定

  • Type: { enabled: boolean; emailConfig?: InvitationEmailConfig; target: string }
  • Description: 招待機能とメールテンプレートを制御します
  • Default: undefined (招待機能は無効)
  • Child Properties:
    • enabled: 招待機能を有効化
      • Type: boolean
      • Description: 招待機能のマスタースイッチ
      • Default: false
      • Required: はい（招待機能を使用する場合）
    • emailConfig: 招待メールテンプレート設定
      • Type: { bodyTemplate: string; subject: string; urlTemplate: string; sender: string }
      • Description: 招待メール用のテンプレート
      • Required: はい（有効な場合）
      • Child Properties:
        • bodyTemplate: HTMLメール本文テンプレート
          • Type: string
          • Description: {{url}}、{{token}}、{{email}}プレースホルダーを含むメール本文用のHTMLテンプレート。urlにはurlTemplateの値が使用されます
          • Example: "<h1>You're invited!</h1><p>Click <a href='{{url}}'>here</a> to accept the invitation.</p>"
        • subject: メール件名
          • Type: string
          • Description: 招待メールの件名
          • Example: "You're invited to join our organization"
        • urlTemplate: 招待リンク用のURLテンプレート
          • Type: string
          • Description: {{token}}と{{email}}プレースホルダーを含むURLテンプレート
          • Example: "https://yourapp.com/invitations/accept?token={{token}}&email={{email}}"
        • sender: 送信者メールアドレス
          • Type: string
          • Description: 招待メールの送信元メールアドレス
          • Required: はい（有効な場合）
          • Example: "invites@yourapp.com"
    • target: 招待検証用のトークンターゲット
      • Type: string
      • Description: 招待トークン検証用のターゲット識別子
      • Default: "invitation"
      • Required: いいえ
      • Example: "invitation"
    • status: 招待ステータス設定
      • Type: { pending?: string; accepted?: string }
      • Description: 招待ステータス用のカスタム識別子
      • Default: undefined (デフォルトのステータス値を使用)
      • Child Properties:
        • pending: 保留中の招待のステータス識別子
          • Type: string
          • Description: 保留中の招待ステータス用のカスタム識別子
          • Example: "pending"
        • accepted: 承認済み招待のステータス識別子
          • Type: string
          • Description: 承認済み招待ステータス用のカスタム識別子
          • Example: "accepted"

設定例​

const authConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret'
  },
  maxFailedLoginAttempts: 3,
  cookieOpts: {
    secure: true,
    sameSite: 'strict',
    maxAge: 2 * 24 * 60 * 60 * 1000 // 2日間
  },
  accessTokenExpireTime: '1h',
  refreshTokenExpireTime: '7d',
  onetimeTokenExpireTime: '30m',
  verifyEmailConfig: {
    enabled: true,
    emailConfig: {
      bodyTemplate: 'Hello {{email}}, click <a href="{{url}}">here</a> to verify your email address.',
      subject: 'Verify your email address',
      urlTemplate: 'https://yourapp.com/verify?token={{token}}'
    },
    sender: 'noreply@yourapp.com'
  },
  invitation: {
    enabled: true,
    emailConfig: {
      bodyTemplate: '<h1>You\'re invited!</h1><p>Click <a href="{{url}}">here</a> to accept the invitation.</p>',
      subject: 'You\'re invited to join our organization',
      urlTemplate: 'https://yourapp.com/invitations/accept?token={{token}}&email={{email}}',
      sender: 'invites@yourapp.com'
    },
    target: 'invitation'
  },
  sendResetPasswordEmailConfig: {
    emailConfig: {
      bodyTemplate: 'Reset your password by clicking ${url}',
      subject: 'Reset your password',
      urlTemplate: 'https://yourapp.com/reset-password?token=${token}'
    },
    sender: 'noreply@yourapp.com'
  },
  resetPasswordSuccessConfig: {
    emailConfig: {
      bodyTemplate: 'Your password has been reset successfully',
      subject: 'Password reset successful',
      urlTemplate: 'https://yourapp.com/auth/callback/reset-password-success'
    },
    sender: 'noreply@yourapp.com'
  },
  changePasswordConfig: {
    emailConfig: {
      bodyTemplate: 'Your password has been changed successfully',
      subject: 'Password change successful',
      urlTemplate: 'https://yourapp.com/auth/callback/change-password-success'
    },
    sender: 'noreply@yourapp.com'
  },
  deactivateIdentityEmailConfig: {
    emailConfig: {
      bodyTemplate: 'Your account has been deactivated',
      subject: 'Account deactivated',
      urlTemplate: 'https://yourapp.com/account-deactivated'
    },
    sender: 'noreply@yourapp.com'
  }
};

🚨 エラーハンドリング​

すべての認証エラーは、適切なHTTPステータスコードと共にJSON形式で返されます：

一般的なエラーコード​

StatusError Message説明
400Validation Error無効なリクエストボディ形式
400verification email feature not enabledメール確認が設定されていません
400verification email feature requires a mail service to be providedメールサービスが設定されていません
400verifyEmailConfig requires emailConfig with fields bodyTemplate, subject, urlTemplateメール設定が不足しています
400Unable to verify token無効な確認トークン
401wrong credentials provided無効なメール/パスワード
401This account is locked失敗試行によりアカウントがロックされました
401Token is not valid access token無効または期限切れのトークン
401Token fails security checkトークンのセキュリティ検証が失敗しました
401token could not be verified認証トークンが欠落しているか無効です
403token does not contain expected dataトークンの検証が失敗しました
403User is not authorized to access this resourceユーザーに必要な権限がありません（管理者アクセス）
404User not foundユーザーが存在しません
404Invitation not found招待が存在しません
409Email already verified or no changes madeメールは既に確認済みです
422unable to register "email"メールが既に存在します
500unable to generate access tokenトークンの生成に失敗しました
500unable to generate refresh tokenリフレッシュトークンの生成に失敗しました
500Failed to send verification emailメール送信プロセスが失敗しました
400/500Failed to create invitation招待の作成に失敗しました

エラーレスポンス形式​

{
  "error": {
    "message": "エラーメッセージの説明",
    "data": ["追加のエラー詳細"]
  }
}

🔗 関連ドキュメント​