認可コードリクエスト
アプリが認可コードを認証サーバに要求するところから認証フローが開始されます。
リクエストを受けた認証サーバは、受け取った情報を元にクライアントとリダイレクトURIを検証し、
ブラウザなどのユーザーエージェントを介して、SPIRAL PLACEユーザーを指定されたアカウントへ
ログインさせ、アプリによるアクセスへの許可/拒否を尋ねます。
この時、ユーザーエージェントが既に指定されたアカウントへのログインセッションを持っていたら
ログインのステップは省略されます。
過去に既に同一ユーザーが当該アプリを許可している場合でもアプリの認証画面は再度表示されます。ただし、スコープが前回許可したものと異なっている場合は新しいスコープで認可情報が上書き
されます。
URL
https://auth.spiral.place/oauth2/authorizationパラメータ
| パラメータ名 | データ型 | 必須 | 説明 |
|---|---|---|---|
| response_type | string | ○ | code を入力 |
| client_id | string | ○ | 登録したアプリのクライアントID |
| redirect_uri | string | ○ | 認可後に遷移するリダイレクトURI |
| scope | string | ○ | 認可を要求するアクセス権限のリスト（スペース区切り） スコープ参照 |
| state | string | リクエストとコールバックの間で状態を維持するために使用するランダムな値 |
認可コードレスポンス
ユーザーがアプリによるアクセスを許可した場合、認証サーバーは認可コードを発行し、指定された
リダイレクトURIのクエリーコンポーネントに以下のパラメーターを付与してユーザーエージェントを
リダイレクトさせます。
https://example.com/callback?code=認可コードパラメータ
| パラメータ名 | データ型 | 説明 |
|---|---|---|
| code | string | 認可コード |
| state | string | ローカルステート リクエストパラメータの値をそのまま返す |
エラーレスポンス
エラー画面
リダイレクトURIの欠落や不正などによって認可リクエストが失敗した場合やクライアントIDが不正な
場合は、リダイレクトURIにリダイレクトせずにエラー画面を表示します。
なお、OAuth 2.0の仕様とは別に、SPIRAL PLACEの仕様に応じて画面上でエラーを表示することも
あります。
| エラーメッセージ | 日本語メッセージ | 説明 |
|---|---|---|
| invalid_redirect_uri | 不正なリダイレクトURIです。 | リダイレクトURIのフォーマット不備があります。 |
| missing_redirect_uri | リダイレクトURIが指定されていません。 | リダイレクトURIが指定されていません。 |
| mismatching_redirect_uri | 不正なリダイレクトURIです。 | アプリ登録時に登録されたリダイレクトURIと異なったリダイレクトURIが指定されています。 |
| invalid_client_id | 不正なクライアントIDです。 | クライアントIDが指定されていないか、存在しないクライアントIDが指定されています。 |
| - | あなたの権限ではこのアプリを利用できません。 | リクエストされたスコープとユーザーの権限（アドミン権限の有無）が一致しません。 |
有効期限エラー画面
アプリの認証画面の有効期限は5分です。有効期限後にアプリの許可または拒否を行った場合は有効期限切れ画面に遷移します。
クエリパラメータエラー
ユーザーがアプリでのアクセスを拒否した場合や、リダイレクトURIの欠落や不正以外の原因で
リクエストが失敗した場合は、リダイレクトURIのクエリに「error」パラメータを追加して
リダイレクトします。
errorパラメータの内容は以下をご参照ください。
| error パラメータ | 説明 |
|---|---|
| invalid_request | パラメータに不足、重複があるか、またはサポート外のパラメータが指定されています。 |
| unauthorized_client | アプリに許可されていないレスポンスタイプが指定されています。 |
| access_denied | ユーザーによってアクセスが拒否されました。 |
| unsupported_response_type | 許可されていないレスポンスタイプです。 |
| invalid_scope | 不正なスコープが指定されています。 |
| server_error | 予期しないエラーが発生しました。 |
| temporarily_unavailable | 一時的に利用できない状況です。 |
トークンリクエスト
認可コードの取得後、アプリは取得した認可コードを含めて、認証サーバにアクセストークンを
リクエストします。
URL
https://auth.spiral.place/oauth2/tokenパラメータ
| パラメータ名 | データ型 | 必須 | 説明 |
|---|---|---|---|
| grant_type | string | ○ | authorization_code を入力 |
| code | string | ○ | 認可サーバーから受け取った認可コード |
| redirect_uri | string | ○ | 認可リクエスト時と同じリダイレクトURI |
| client_id | string | ○ | 登録したアプリのクライアントID |
| client_secret | string | ○ | 登録したアプリのクライアントシークレット（パスワード） |
※ クライアントシークレットはクライアントの認証を行うためのパスワードです。
公開されたソースコード内や、アプリユーザーが閲覧できる場所に表示しないでください。
トークンレスポンス
トークンリクエストを受け取った認証サーバはリクエストを検証し、問題がなければアクセス
トークン、リフレッシュトークンなどの認可情報をアプリへ返します。
パラメータ
アクセストークンの発行に成功した場合は、レスポンスボディに以下のパラメーターを付与し、
HTTPステータスコード 200 (OK) でレスポンスを返します。
| パラメータ名 | データ型 | 説明 |
|---|---|---|
| access_token | string | 認可サーバーが発行するアクセストークン 40～50文字のランダムな文字列 |
| expires_in | number | アクセストークンの有効期限（秒） |
| refresh_token | string | リフレッシュトークン 40～50文字のランダムな文字列 |
| token_type | string | Bearer を入力 |
| scope | string | 許可されたスコープ |
※ アクセストークンの有効期限は1時間、リフレッシュトークンの有効期限は90日です。
エラーレスポンス
トークン取得時のエラーは、HTTPレスポンスボディにJSON形式で「error」パラメータを追加して
返されます。
ステータスコードとerrorパラメータの内容は以下をご参照ください。
| error パラメータ | ステータスコード | 説明 |
|---|---|---|
| invalid_request | 400 | パラメータに不足、重複があるか、またはサポート外のパラメータが指定されています。 |
| invalid_client | 401 | クライアントの認証に失敗しました。クライアントIDまたはクライアントシークレットが指定されていないか不正です。 もしくはサポートされない認証方式が利用されています。 |
| invalid_grant | 401 | 認可コードまたはリフレッシュトークンが不正です。 |
| unauthorized_client | 400 | 許可されていない認証方式が利用されています。 |
| unsupported_grant_type | 400 | 許可されていない認証方式が利用されています。 |
| invalid_scope | 401 | 不正なスコープが指定されています。 |
アクセストークン更新
SPIRAL PLACE APIではリフレッシュトークンに対応しています。
取得したアクセストークンの有効期限は1時間ですが、リフレッシュトークンを利用することで、
認可コードによる認証を再度行うことなく、新しいアクセストークンを取得することができます。
URL
https://auth.spiral.place/oauth2/tokenパラメータ
| パラメータ名 | データ型 | 必須 | 説明 |
|---|---|---|---|
| grant_type | string | ○ | refresh_token を入力 |
| refresh_token | string | ○ | アプリに発行されたリフレッシュトークン |
| client_id | string | ○ | 登録したアプリのクライアントID |
| client_secret | string | ○ | 登録したアプリのクライアントシークレット（パスワード） |
| scope | string | 認可を要求するアクセス権限のリスト（スペース区切り） スコープ参照 元々許可されたスコープと同一のものを指定 |
アクセストークン更新レスポンス
「トークンレスポンス」をご参照ください。
アクセストークンの破棄
ユーザーは一度アプリに与えたアクセス許可を管理画面より破棄する（取り消す）ことができます。
スタッフプレースにログインし、「個人設定」の「アプリ管理」よりアクセス許可したアプリの確認
及び許可の取り消しを行うことができます。