1. OAuth認証

ヤマレコの投稿用APIなどの一部のAPIを利用する場合、OAuth 2.0をベースとした認証が必要になります。

OAuth 2.0の仕様に関しては、各種ドキュメントを参照してください。

１）アプリケーションの登録

２）アプリケーション上の認証処理

1. アプリケーションの登録

※現在は個人で使う目的のアプリケーションや、ハッカソン・学校等の課題や研究などの目的のアプリケーションは受け付けておりません。また、データの書き出し・収集・分析をするなど、利用規約の違反行為や経営上の判断で許可できない場合もありますのでご了承ください。

OAuth認証が必要なAPIを利用する場合、以下のページから、作成するアプリケーションおよびリダイレクト先URLを登録してください。

https://www.yamareco.com/modules/liaise/?form_id=18

リダイレクト先URLは、Webサイトの場合はOAuth認証の際のリダイレクト先URL、URLを持たないモバイルアプリケーションなどの場合はアプリケーションのコールバック用URI（例えば、sample.yamareco.com://callback など）を指定してください。

登録いただいた内容を確認後、アプリケーションのクライアントIDおよびクライアントシークレットを発行いたします。

発行に時間がかかる場合がありますので、早めに申請されることをおすすめします。

※申請時に白紙のページが表示されてしまう場合は、申請に失敗しています。

その場合は、お手数ですが下記まで、申請項目をメールでご連絡ください。

2. アプリケーション上の認証処理

アプリケーションでは以下の３ステップを踏んで頂く必要があります。

1. 認可コードの取得

2. アクセストークンの取得

3. REST APIへのアクセス

また、コードの取得およびアクセストークンの取得ではCookieを利用しますので、特にブラウザをベースとしないアプリケーションにおいても、上記の通信時にCookieが利用できるような実装をお願いいたします。

2.1 認可コードの取得

下記のアドレスにHTTPS GETリクエストを送信します。

https://api.yamareco.com/api/v1/oauth?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URL>&response_type=code&scope=all

- <CLIENT_ID>: アプリケーション登録時に取得したクライアントID

- <REDIRECT_URL>: アプリケーション登録時に記入したリダイレクト先URL

ブラウザを経由して、利用者がヤマレコにログインし、本人が許可した場合のみリダイレクト先URLに認可コードが通知されます。例えばリダイレクト先にhttp://my.webservice.com/とした場合、http://my.webservice.com/?code=<CODE>へのリダイレクトになります（<CODE>はサーバが発行した認可コード）

※ブラウザのデータキャッシュを禁止するHTTPヘッダをサーバから返却していますが、ブラウザがキャッシュを読み込んでしまう場合は、タイムスタンプなどのパラメータ（例： &ts=<TIMESTAMP>)をURLに追加いただければキャッシュを防止できます。

2.2 アクセストークンの取得

下記のアドレスにHTTPS POSTリクエストを送信します。

https://api.yamareco.com/api/v1/oauth/access_token

- client_id: アプリケーション登録時に取得したクライアントID

- client_secret: アプリケーション登録時に取得したクライアントシークレット

- redirect_uri: アプリケーション登録時に記入したリダイレクト先URL

- code: 前の手順で取得した認可コード

- grant_type: "authorization_code"という固定文字列

レスポンス:  リダイレクトURLがHTTPのLocationヘッダ内に設定され、JSON形式で以下の応答があります。

- access_token: アクセストークンの発行に成功した場合のトークン番号

- error: エラーなし(0)、エラーあり(1)

- error_message: エラーが起きたときに表示されるメッセージ

レスポンスのサンプル

{"access_token":"5d393ec8c36122523baf7a966c21a647faeba8aa","error":0,"error_message":""}

2.3 REST APIへのアクセス

APIへのGET/POSTアクセスの際に、HTTPのAuthorizationヘッダとして、認証スキームとして"OAuth "の文字、および上記で取得したアクセストークンを値として設定した上でサーバに送信してください。

[例] Authorization: OAuth 5d393ec8c36122523baf7a966c21a647faeba8aa

アクセストークンのチェックに失敗した場合、サーバからHTTPの403エラーが返答されます。

なお、個別のAPI仕様はAPI仕様のページにてご確認ください。

2.4 アクセストークンの再発行

サーバ側の認可情報が削除された場合、認可コードおよびアクセストークンの再取得が必要になります。

2.5 サインアウト処理

ユーザIDの変更などでサインアウトが必要な場合は、ブラウザを使って下記のアドレスにHTTPS GETリクエストを送信すれば、セッションが破棄されてサインアウトが完了します。

https://api.yamareco.com/api/v1/oauth/sign_out&redirect_uri=<REDIRECT_URL>

- <REDIRECT_URL>: アプリケーション登録時に記入したリダイレクト先URL（省略可。省略時はリダイレクトされずにログアウト完了メッセージのページが表示される）