認証かたデータの取得・編集まで
流れ
- Toodledoの認証ページに遷移
- ユーザーが、Toodledoアカウントにサインインして、アプリを承認
- 認証コードと共にアプリケーションにリダイレクト
- アプリケーションの秘密鍵を使って、トークン（とリフレッシュトークン）を取得
- トークンをアプリに保管し、これを使ってAPIリスエストを実行する。
- トークンが失効したら、リフレッシュトークンを使って新しいトークンを取得する。
- リフレッシュトークンも失効したら、最初の認証からやり直し。
1.遷移
https://api.toodledo.com/3/account/authorize.php?response_type=code&client_id=YourClientID&state=YourState&scope=basic%20tasks
scopeの種類
- basic - アカウント情報
- tasks - タスク
- notes - ノート
- outlines - アウトライン
- lists - リスト
- share - 共同作業者の情報
- write - 上記の情報の編集を許すかどうか
2.Toodledoのサイトでアプリを承認
Toodledoのユーザが、アプリケーションによるToodledoデータの操作を承認したら、（Toodledo上で登録した）リダイレクトURLへ遷移される。このとき、URIとしては、以下の情報が与えられる。
- code : 次のステップでアクセストークンを手に入れるためのコード
- state : 承認のリクエストが来た際のstate情報。cross site request forgery を避けるために使用する。
- error : 何かしらのエラー（ユーザーが要求を棄却したとか）がある場合はここに記録される。
REDIRECT_URI?code=49075c51ed30133f909f7c0dd03996e8f395be57&state=YourState
Javaなら、HttpServletRequest requestで
request.getParameter("hoge")
リダイレクトのあ使い方には２種類ある。
- プロジェクトにカスタムURLをセットして、処理させる
- これは、デバイスに "myToodledoApp://authorize" のような支持を出して、アプリケーションを起動させるような使い方。You would redirect the user to the device's built in web browser and the web browser will automatically launch your app with the authorization code in your apps launch options.
- カスタムWEBヴューをつくる
- The second option is to keep the user in your app by implementing a custom web view (like an iframe) that contains our authorization page. You can then override the redirect method and grab the returned URL without actually fetching it. In this case the redirect URI would never be called, so it doesn't need to be an actual valid URI, although for obvious security reasons you should not have the Redirect URI go to valid URL not controlled by you.
There are OAuth2 libraries for iOS,
Android and other platforms that can help with this and we have provided some sample code as well.
3.リダイレクトとパラメータ
パラメータとともに元ページにリダイレクトされてくる。
リダイレクト先はToodledoに登録しておく。
どこのサイトを書いても、後に code=aaaa&state=bbbbのようについて来る
パラメータ
- code : アルファベットの文字列のコード。次のステップでアクセスするトークンを取得するのに用いる
- state : 認証リクエストにともに送った state。cross site request forgery を避けるために、自分で送った state を比較し確認する。
- error : 認証リクエストが拒否されたりエラーを起こした場合に、この文字列が表示される。
トークンの取得
認証コードの取得後、トークンとの交換を行う。
SSLで暗号化されたリクエストを クライアントIDと秘密鍵と認証コードを使って/3/account/token.php にポスト(POST)する。
そのレスポンスはアクセストークンとリフレッシュトークンを含んでいる。
トークンのリクエスト時に、アプリケーションの幾つかの情報を送ることもできる。
それらは分析ページで見ることができる。つまり、どんなデバイスが使われるかなどの分析ができる。
クライアントIDと秘密鍵はそれぞれ、client_id、client_secret、として、下記のパラメータと同じようにしても渡せる。
Javaでのプログラミング
パラメータ
- grant_type : "authorization_code"という文字列.（必須）
- code : 認証コード（必須）
- vers : アプリケーションのバージョン。整数値。（任意）
- device : アプリケーションが動作しているデバイス／プラットフォーム（任意）
- os : アプリケーションが走っているOSのバージョン。整数値。（任意）
- f : レスポンスのフォーマット。json か xml。デフォルトはjson（任意）
レスポンス
- access_token : アルファベット文字列
- expires_in : アクセストークンの有効期限。7200秒の固定（のはず）
- token_type : なに？Bearer
- scope : スコープ。スペース区切りの文字列
- refresh_token : アルファベット文字列
リフレッシュトークン
access_tokenが時間切れで失効した場合には、refresh_tokenを使って新しいaccess_tokenを取ってくる。
refresh_tokenの有効期限は30日。これが切れたら認証し直し。
- POST先は通常のToken取得と同じ
- basic認証も必要
パラメータ
- grant_type : "refresh_token"という文字列.（必須）
- refresh_token : refresh_token（必須）
- vers : アプリケーションのバージョン。整数値。（任意）
- device : アプリケーションが動作しているデバイス／プラットフォーム（任意）
- os : アプリケーションが走っているOSのバージョン。整数値。（任意）
- f : レスポンスのフォーマット。json か xml。デフォルトはjson（任意）
エラーコード
token API endpointから受け取るエラーコード（メッセージ）
Here is a list of the error messages that you may receive from the token API endpoint.
- 101 : SSLで接続していない
- 102 : There was an error requesting a token.
- 103 : トークンのリクエスト数が上限を超えた
サンプル
JSON:
{"errorCode":101,"errorDesc":"SSL connection required"}
XML:
<error id="101">SSL connection required</error>
最終更新：2017年09月29日 22:42
