自分以外の利用者のアカウントでAnnict APIを使うアプリを作るときは、OAuthで認証します。
利用者はAnnictの認可ページでアプリを承認し、アプリはその結果として受け取った認証コードをアクセストークンと交換します。
自分のアカウントのデータを読み書きするだけであれば、Annict APIの個人用アクセストークンのほうが手軽です。
このページでは、利用者がブラウザで開く認可ページを https://annict.com、アクセストークンを扱うエンドポイントを https://api.annict.com として説明します。
クライアントアプリケーションを作成する
OAuthで使用するクライアントIDなどを保持するクライアントアプリケーションを作成します。
- Annictにログインした状態でアプリケーションの一覧ページを開きます
- 「新規登録」ボタンを押します
- 「アプリケーション名」に、利用者へ表示されるアプリの名前を入力します
- 「リダイレクトURI」に、認可後に戻ってくるURIを入力します
- 「スコープ」で「読み込み専用」か「読み込み + 書き込み」を選びます
- 「登録」ボタンを押します
リダイレクトURIは改行で区切って複数指定できます。
ローカルで動くアプリ向けに urn:ietf:wg:oauth:2.0:oob も指定できます。
登録するとアプリケーションの詳細ページが開き、クライアントID・クライアントシークレット・スコープ・リダイレクトURIが表示されます。
クライアントシークレットは他人に知られないように扱ってください。
認可のリクエストを送る (GET /oauth/authorize)
Annict APIが提供するリソースにどのような権限でアクセスするかを利用者に確認するため、認可のためのリクエストを送ります。
利用者のブラウザでこのURIを開くと、アクセス許可を求めるページが表示されます。
パラメータ
| 名前 | 概要 |
|---|---|
| client_id | [必須] クライアントID。作成したクライアントアプリケーションのクライアントIDになります。 |
| response_type | [必須] 認可後にコールバックで返ってきたときのURIに付与される認証コードのパラメータ名。code を指定してください。 |
| redirect_uri | [必須] 認可後のコールバックでどのURIに返るかを指定します。クライアントアプリケーションに登録したURIのいずれかを指定してください。urn:ietf:wg:oauth:2.0:oob を指定した場合、認可後にリダイレクトせず認証コードが表示されます。 |
| scope | リソースにアクセスする際の権限を指定します。デフォルトは read (読み込み専用) になっています。書き込み権限も付与したい場合は read write を指定してください。 |
| state | 任意の文字列を指定すると、認可後のコールバックにそのまま返されます。リクエストの改ざんを検知するために使えます。 |
リクエスト例
下記の例では redirect_uri に urn:ietf:wg:oauth:2.0:oob が指定されているため、認可後のページに認証コードが表示されます。
GET https://annict.com/oauth/authorize?client_id=f96b162be2c54b467f7583a0e141d0df99bf16318146f9bf53116d82b145fde6&response_type=code&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=read+write
下記の例では redirect_uri に http://example.com が指定されているため、認可後に http://example.com/?code=xxx というページにリダイレクトされます。
パラメータ code に渡されている値が認証コードになります。
GET https://annict.com/oauth/authorize?client_id=f96b162be2c54b467f7583a0e141d0df99bf16318146f9bf53116d82b145fde6&response_type=code&redirect_uri=http://example.com&scope=read+write
アクセストークンを取得する (POST /oauth/token)
認可後に取得した認証コードを使用して、アクセストークンを発行します。
発行したアクセストークンに有効期限はありません。
リフレッシュトークンも発行されないため、失効させるまで同じアクセストークンを使い続けられます。
パラメータ
| 名前 | 概要 |
|---|---|
| client_id | [必須] クライアントID。 |
| client_secret | [必須] 作成したクライアントアプリケーションのクライアントシークレット。 |
| grant_type | [必須] authorization_code を指定してください。 |
| redirect_uri | [必須] 認可のリクエストで指定したものと同じコールバックURIを指定します。 |
| code | [必須] 認可後に取得した認証コードを指定します。 |
リクエスト例
$ curl -F client_id=f96b162be2c54b467f7583a0e141d0df99bf16318146f9bf53116d82b145fde6 \
-F client_secret=9bef7fc39d5d6210ecaaa34d8ccfe5e7a10babd2ebad90876307d71a8e14de69 \
-F grant_type=authorization_code \
-F redirect_uri=http://example.com \
-F code=82c0436de2b586ca974b45ab4e12ceeeeda2a8cf90a269b2dbc5a24c4a6fc8f2 \
-X POST https://api.annict.com/oauth/token
レスポンス例
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"access_token": "58468586b6f4c29e88a8d9b7f3babb8364fec9991f2681081cbfd849d7c11a91",
"token_type": "Bearer",
"scope": "read write",
"created_at": 1465718311
}
アクセストークンの情報を取得する (GET /oauth/token/info)
アクセストークンの情報を取得します。
Authorization ヘッダにアクセストークンを渡してリクエストを送ります。
リクエスト例
$ curl -H "Authorization: Bearer 35372b2d866222ed33e355c36d86be498076e037a810ee72963819339c781f32" \
-X GET https://api.annict.com/oauth/token/info
レスポンス例
expires_in は有効期限までの秒数ですが、Annictのアクセストークンは期限切れにならないため常に null になります。
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"resource_owner_id": 2,
"scope": ["read", "write"],
"expires_in": null,
"application": {
"uid": "bfa6272ede7f7d096099c4e5f15923a78630520435169f47006e18d5e4dc2a7e"
},
"created_at": 1461949248
}
アクセストークンを失効させる (POST /oauth/revoke)
アクセストークンを失効させます。
Authorization ヘッダと token パラメータを渡してリクエストを送ります。
パラメータ
| 名前 | 概要 |
|---|---|
| client_id | [必須] クライアントID。 |
| client_secret | [必須] 作成したクライアントアプリケーションのクライアントシークレット。 |
| token | [必須] 失効させるアクセストークンを指定します。 |
リクエスト例
$ curl -H "Authorization: Bearer 35372b2d866222ed33e355c36d86be498076e037a810ee72963819339c781f32" \
-F client_id=f96b162be2c54b467f7583a0e141d0df99bf16318146f9bf53116d82b145fde6 \
-F client_secret=9bef7fc39d5d6210ecaaa34d8ccfe5e7a10babd2ebad90876307d71a8e14de69 \
-F token=35372b2d866222ed33e355c36d86be498076e037a810ee72963819339c781f32 \
-X POST https://api.annict.com/oauth/revoke
レスポンス例
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{}