DJ の同意を得る

このページのとおりに進めると、DJ を Spoon の同意画面に送り、DJ が許可した後に戻ってくる値を受け取れます。戻ってきた値に含まれる code で、次のステップでトークンを受け取ります。

準備するもの

登録済みアプリの Client ID — アプリ登録で受け取ります。
アプリに登録した ログインリダイレクト URL — ここに DJ が戻ってきます。

全体の流れ

自分のボットサーバー ──▶ DJ のブラウザを authorize アドレスに送ります
                              │
                              ▼
                        Spoon がログインと同意画面を担当します
                              │
                              ▼
自分のリダイレクト URL ◀── ブラウザが code または error を付けて戻ります

ログイン画面と同意画面は Spoon が表示します。自分のサーバーがすることは、送ることと 戻ってきた値を受け取ることの 2 つです。

1. DJ を同意画面に送ります

DJ のブラウザを下のアドレスに移動させます。サーバー同士で呼ぶ API ではなく、ブラウザが直接開くアドレスです。

https://developers.spooncast.net/jp/oauth/authorize
  ?response_type=code
  &client_id={Client ID}
  &redirect_uri={ログインリダイレクト URL}
  &scope=events.chat%20chat.send
  &state={自分で作ったランダムな値}

アドレスにリージョンを入れます。 韓国のアプリは /kr、日本のアプリは /jp です。

リージョン	authorize アドレス
韓国	`https://developers.spooncast.net/kr/oauth/authorize`
日本	`https://developers.spooncast.net/jp/oauth/authorize`

自分のアプリが登録されているリージョンを使います。別のリージョンのアドレスに送ると、DJ はそのリージョンのアカウントでログインする必要があるため、同意画面にたどり着けません。

パラメータ	必須	ルール
`response_type`	必須	`code` のみ受け付けます。
`client_id`	必須	アプリ詳細画面の Client ID です。
`redirect_uri`	必須	アプリに登録したアドレスと一字も違わず一致する必要があります。違うと同意画面にエラーが出て、自分のアドレスには戻りません。
`scope`	必須	要求する権限を半角スペースでつなげて書きます。アドレスに載せるときは `%20` にエンコードします。アプリに登録していない権限は拒否されます。
`state`	推奨	リクエストごとに新しく作るランダムな値です。戻るときにそのまま載って来るので、照合して偽造リクエストを弾きます。512 バイトまで受け付けます。

ログインしていない DJ もそのまま送ります。Spoon がログインを受け付けた後、同意画面へつなぎます。

同じ権限にすでに同意した DJ は、画面を見ずにそのまま戻ります。同意は積み上がるため、新しく要求した権限だけが画面に出ます。

2. 戻ってきた値を受け取ります

DJ のブラウザが redirect_uri に戻ります。成功と失敗はクエリで見分けます。

DJ が許可すると code が載ります。

https://my-bot.example.com/callback?code=9d41f7a0c86b23e5...&state=自分が送った値

値	使いみち
`code`	トークンに交換する 1 回限りの値です。60 秒以内に使います。
`state`	自分が送った値そのままです。違えばそのリクエストを捨てます。

DJ が拒否したり、リクエストが誤っている場合は code の代わりに error が載ります。

https://my-bot.example.com/callback?error=access_denied&state=自分が送った値

`error`	何が起きたか	どうするか
`access_denied`	DJ が許可しませんでした。	連携を止めて DJ に案内します。もう一度試しても構いません。
`invalid_scope`	アプリが持っていない権限を要求しました。	`scope` をアプリに登録した権限に絞ります。もう一度送っても同じ結果です。

error が来ない失敗もあります。 client_id や redirect_uri が信頼できないときは、自分のアドレスに戻さず Spoon の同意画面にエラーを表示します。登録していないアドレスへユーザーを送らないためのルールです。この場合 DJ は自分のサービスに戻らないので、値を送る前に Client ID とリダイレクト URL を確認します。

確認する方法

ブラウザで authorize アドレスを直接開きます。次のとおりになれば連携は正しいです。

Spoon のログイン画面が出るか、ログイン済みならすぐ同意画面が出ます。
要求した権限のうち、まだ同意していないものだけが一覧に出ます。
許可を押すと、自分の redirect_uri に code と state が載って戻ります。

同意画面ではなくエラー文が見える場合は、client_id と redirect_uri をもう一度確認します。

次のステップ

受け取った code をトークンに交換します。code は 60 秒。 以内に使う必要があり、一度使った値は再利用できません。

準備するもの​

全体の流れ​

1. DJ を同意画面に送ります​

2. 戻ってきた値を受け取ります​

確認する方法​

次のステップ​