ユーザー認証リクエストAPI
Vivoldi REST APIでユーザー情報の取得や設定変更を行う前に、認証用のアクセストークンを発行してください。
有効期限付きのトークンベース認証により、アカウントのセキュリティを強化し、外部からの不正アクセスを防ぎます。
発行されたトークンをX-Access-Tokenヘッダーに設定することで、安全にAPIを呼び出せます。
このAPIはパーソナルプラン以上で利用できます。
POST
/api/user/v1/auth
{
"eml": "your@gmail.com"
}Request Parameters
- eml string
-
メールアドレス。
ビジネスプラン以上で、組織内に追加されたユーザー情報を照会または変更する際に指定します。
パーソナルおよびプレミアムプランでは、この値は無視されます。
{
"code": 0,
"message": "",
"result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Response Parameters
- code integer
- 応答コード: 0 = 成功、それ以外の値 = エラー
- message string
- 応答メッセージです。応答コードが0でない場合、エラーメッセージが返されます。
- result string
-
ユーザー情報の照会および更新を行う際は、HTTPヘッダーの
X-Access-Token項目に追加する必要があります。
トークンは1分間有効で、有効期限後は再発行（本APIの再呼び出し）が必要です。
認証トークンが必要な理由
すべてのAPIリクエストは、ユーザーの識別と権限確認のために認証が必要です。
このAPIは以下の役割を担います。
- API呼び出し元の識別
- ユーザー権限の検証
- 不正リクエストの遮断
- セキュアなセッション状態の管理
このAPIを利用するタイミング
<p>
本APIは、<a href="/url/api/user/retrieve">ユーザー情報取得</a>や<a href="/url/api/user/update">情報更新</a>など、アカウントデータにアクセスする前に必ず実行する必要があります。
</p>
<p>
発行されたトークンは、すべてのリクエストのHTTPヘッダー<code>X-Access-Token</code>に含めて送信してください。
短い有効期限によりセッション露出を最小限に抑え、セキュリティを維持します。
</p>
トークン有効期限1分の意味
1分という短い有効期限は、セキュリティを重視した設計です。
トークンが漏洩した場合でも、1分以内に自動的に失効し、リスクを最小限に抑えます。
推奨される実装は、API呼び出し直前にトークンを発行し、即時に使用することです。
トークンを保存して再利用すると、認証エラーの原因になります。
対象指定方法とプラン条件
ビジネスプラン以上では、組織管理者がemlパラメータに対象ユーザーのメールアドレスを指定することで代理認証が可能です。
これにより、組織内ユーザーの情報取得や管理の自動化が実現できます。
本APIはパーソナルプラン以上でのみ利用可能なため、事前にプランをご確認ください。
利用時の注意点
- トークンは外部に漏洩しないよう安全に管理してください
- クライアント側でトークンを直接扱う構成はセキュリティリスクがあります
- トークン失効時には自動再発行の仕組みを実装してください
- 必ずHTTPS環境で利用してください