アプリ専用認証と OAuth 2.0 ベアラートークン

​

アプリのみの認証と OAuth 2.0 ベアラートークン

X では、特定のユーザーではなくアプリケーション自体の名義で認証済みリクエストを発行できます。X の実装は、OAuth 2 仕様のクライアントクレデンシャルグラントフローに基づいています。

アプリのみの認証はユーザーコンテキストを一切含まず、アプリが自身の名義で API リクエストを行う認証方式です。公開情報への読み取り専用アクセスのみが必要な開発者向けの方法です。 

アプリのみの認証は、アプリのコンシューマ API キー、または App only アクセストークン（ベアラートークン）を用いて実行できます。つまり、X API に対して行えるのは、認証済みユーザーを必要としないリクエストに限られます。

アプリのみの認証で可能な操作:

• ユーザーのタイムラインの取得
• 任意のアカウントのフォロー中/フォロワーへのアクセス
• リスト関連リソースへのアクセス
• Tweet の検索

ユーザーに代わってリクエストを発行するには、OAuth 1.0a または PKCE を用いた OAuth 2.0 Authorization Code Flow が必要です。API リファレンス ページでは、各 API の利用に必要な認証方式を説明しています。次の操作を行うには、アクセス トークン を用いたユーザー認証（ユーザーコンテキスト）が必要です:

• Tweet またはその他のリソースの投稿
• ユーザーの検索
• いずれかのジオエンドポイントの使用
• ダイレクトメッセージまたはアカウント資格情報へのアクセス
• ユーザーのメールアドレスの取得

​

認証フロー

この方法を使用するには、App only Access Token（Bearer Token とも呼ばれます）を使用する必要があります。POST oauth2/token エンドポイントにコンシューマーキーとシークレットを渡すことで、App only Access Token（Bearer Token）を生成できます。

アプリケーションのみの認証フローは次の手順で行います。

• アプリケーションは、コンシューマーキーとシークレットを特別な形式でエンコードした資格情報に変換します。
• アプリケーションは、POST oauth2/token エンドポイントにリクエストを送り、これらの資格情報を App only Access Token と交換します。
• REST API にアクセスする際、アプリケーションは App only Access Token を使用して認証します。

リクエストに署名する必要がないため、この方法は標準的な OAuth 1.0a モデルよりもはるかに簡潔です。

​

アプリのみ認証について

トークンはパスワードです

コンシューマーキーとシークレット、そしてアプリのみのアクセス トークン（Bearer Token）自体には、アプリケーションを代表してリクエストを実行する権限があります。これらの値はパスワードと同等の機密情報として扱い、信頼できない第三者と共有・配布してはなりません。

SSL は必須

すべてのリクエスト（トークンの取得・使用の両方）は、HTTPS エンドポイントを使用しなければなりません。TLS を使用して X API に接続するに記載のベストプラクティスに従ってください。ピアの検証は常に行う必要があります。

ユーザーコンテキストなし

アプリのみ認証でリクエストを発行する場合、「現在のユーザー」という概念はありません。したがって、POST statuses/update のようなエンドポイントは、アプリのみ認証では機能しません。ユーザーを代表してリクエストを発行する方法の詳細は、OAuth の使用を参照してください。

レート制限

アプリケーションには 2 種類のレート制限プールがあります。

ユーザーコンテキスト（アクセス トークンを用いてユーザーの代理で行うリクエスト）は、アプリのみ認証で使用されるものとは異なるレート制限コンテキストから消費されます。言い換えると、ユーザーの代理で行うリクエストはアプリのみ認証で利用可能なレート制限を消費せず、アプリのみ認証で行うリクエストはユーザー ベース認証で使用されるレート制限を消費しません。

API のレート制限の詳細と制限の確認をご覧ください。

​

アプリのみのリクエストの発行

ステップ 1: consumer key と secret をエンコードする

アプリの consumer key と secret を一組の認証情報にエンコードして Bearer Token を取得する手順は次のとおりです。

1. RFC 1738 に従って consumer key と consumer secret を URL エンコードします。執筆時点では、これは実際には consumer key と secret を変更しませんが、将来的にそれらの値の形式が変わる可能性に備えて、この手順は実施してください。
2. エンコード済みの consumer key、コロン文字「:」、エンコード済みの consumer secret を連結して 1 つの文字列にします。
3. 前の手順で作成した文字列をBase64 エンコードします。

以下は、このアルゴリズムの結果を示す例です。このページで使用している consumer secret はテスト用であり、実際のリクエストでは使用できません。

Consumer key	xvz1evFS4wEEPTGEFPHBog
Consumer secret	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
RFC 1738 encoded consumer key (does not change)	xvz1evFS4wEEPTGEFPHBog
RFC 1738 encoded consumer secret (does not change)	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Bearer Token credentials	xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Base64 encoded Bearer Token credentials	:: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==

ステップ 2: アプリのみの Access Token（Bearer Token）を取得する

ステップ 1 で計算した値は、POST oauth2/token にリクエストを送信して、アプリのみの Access Token と交換する必要があります。

• リクエストは HTTP POST である必要があります。
• リクエストには Authorization ヘッダーを含め、その値は Basic <base64 encoded value from step 1>. とする必要があります。
• リクエストには Content-Type ヘッダーを含め、その値は application/x-www-form-urlencoded;charset=UTF-8. とする必要があります。
• リクエストのボディは grant_type=client_credentials である必要があります。

リクエスト例（Authorization ヘッダーは折り返して表示しています）：

POST /oauth2/token HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip

grant\_type=client\_credentials

リクエストが正しくフォーマットされていれば、サーバーはJSONエンコードされたペイロードで応答します。

レスポンス例:

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140

{"token\_type":"bearer","access\_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

アプリケーションは、返却されたオブジェクトの token_type キーに対応する値が bearer であることを確認する必要があります。access_token キーに対応する値が、アプリ専用アクセス・トークン（Bearer Token）です。

1つのアプリ専用アクセス・トークンは、同時に1つのアプリケーションに対してのみ有効である点に注意してください。同じ認証情報で /oauth2/token に再度リクエストしても、無効化されるまでは同じトークンが返されます。

ステップ3: アプリ専用アクセス・トークン（Bearer Token）で API リクエストを認証する

アプリ専用アクセス・トークン（Bearer Token）は、アプリケーション専用認証をサポートする API エンドポイントへのリクエストに使用できます。アプリ専用アクセス・トークンを使用するには、通常の HTTPS リクエストを作成し、Authorization ヘッダーに Bearer <step 2 で取得した base64 の bearer トークン値>。署名は不要です。 を含めてください。

リクエスト例（Authorization ヘッダーは折り返し表示）:

GET /1.1/statuses/user\_timeline.json?count=100&screen\_name=twitterapi HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA
                      AAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip

アプリ専用アクセス トークン（ベアラー トークン）の失効

アプリ専用アクセス トークンが漏えいした、または何らかの理由で失効させる必要がある場合は、POST oauth2/invalidate_token を呼び出してください。

リクエスト例（Authorization ヘッダーは折り返して表示しています）：

POST /oauth2/invalidate_token HTTP/1.1
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
User-Agent: My X App v1.0.23
Host: api.x.com
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded

access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

レスポンスの例：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 127
...

{"access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

​

よくあるエラーケース

このセクションでは、Bearer Token のやり取りや使用時に起こりやすい誤りについて説明します。ここに挙げるのは考えられるすべてのエラーレスポンスではありません。未処理のエラーコードやレスポンスにも注意してください。

アプリのみアクセス トークン（Bearer Token）の取得・失効に関する無効なリクエスト

以下の試み:

• 無効なリクエストでアプリのみアクセス トークン（Bearer Token）を取得する（例: grant_type=client_credentials を省略する）。
• 誤っている、または期限切れのアプリ資格情報でアプリのみアクセス トークン（Bearer Token）を取得または失効させる。
• 誤っている、またはすでに失効済みのアプリのみアクセス トークン（Bearer Token）を無効化する。
• 短時間に過度な頻度でアプリのみアクセス トークン（Bearer Token）を取得する。

は、次の結果につながります:

HTTP/1.1 403 Forbidden
Content-Length: 105
Content-Type: application/json; charset=utf-8
...

{"errors":\[{"code":99,"label":"authenticity\_token\_error","message":"認証情報を確認できません"}\]}

​

API リクエストに無効なアプリ専用アクセス トークン（ベアラー トークン）が含まれています

誤った、または失効したアクセス トークンで API リクエストを行うと、次のようになります。

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 61
...

{"errors":[{"message":"無効または期限切れのトークン","code":89}]}

​

アプリのみアクセス トークン（Bearer トークン）を、アプリケーションのみ認証をサポートしないエンドポイントで使用した場合

ユーザーコンテキストが必要なエンドポイント（statuses/home_timeline など）に、アプリのみアクセス トークン（Bearer トークン）でリクエストすると、次のようになります：

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":\[{"message":"ご利用の認証情報ではこのリソースにアクセスできません","code":220}\]}