開発者用 App

​

概要

既存の App がある場合は、developer portal の App ページから表示、編集、または削除できます。

X API および X Ads API にアクセスするには、各リクエストに付与する必要がある authentication の資格情報（キーおよびトークンとも呼ばれます）が必要です。これらの資格情報は、使用する特定の endpoint が要求する認証方式に応じて異なる形式になります。

以下は、App で生成できる各種資格情報とその使用方法です。

• API Key and Secret： 本質的には App のユーザー名とパスワードに相当します。OAuth 1.0a ユーザーコンテキストを必要とするリクエストの認証や、ユーザー Access Tokens や App Access Token など他のトークンの生成に使用します。

• Access Token and Secret： 一般に、Access Tokens はあなたが代理してリクエストを行うユーザーを表します。developer portal で生成できるものは、App の所有者であるユーザーを表します。これらは OAuth 1.0a ユーザーコンテキストを必要とするリクエストの認証に使用します。別のユーザーの代理でリクエストする場合は、そのユーザーに認可してもらうために 3-legged OAuth フローを使用する必要があります。

• Client ID and Client Secret： これらの資格情報は、OAuth 2.0 認証でユーザーの Access Token を取得するために使用します。OAuth 1.0a と同様に、ユーザー Access Tokens は非公開のユーザーアカウント情報を提供するリクエストの認証や、他アカウントの代理での操作に使用されますが、クライアントアプリケーションがユーザーに対して持つアクセス権をより細かく制御できるスコープが適用されます。

• App only Access Token： X 上で公開されている情報を返す endpoint へのリクエスト時に使用します。

X API リクエストに必要なキーおよびトークンを生成することに加えて、permissions を設定し、App のユースケースまたは目的を記録し、callback URL を定義し、management dashboard から App の開発環境に関するその他の設定を変更することもできます。

​

App と Project

ユースケースごとに作業を整理するために、X Developer Platform では App とProjectを利用できます。各 Project には、Free の X API プランでは 1 つの App、Basic プランでは最大 2 つ、Pro プランでは最大 3 つの App を含められます。

新しい X API v2 の endpoint にアクセスするには、Project に紐づく App のキーおよびトークンを使用する必要があります。

Project を導入する前に作成した App は、“Standalone Apps” というセクションに表示されます。Standalone Apps は Project 構造外の App を指します。Standalone App を Project に紐づけると、v2 の endpoint にリクエストを送信できるようになります。

​

developer portal のダッシュボード

アカウントに関連付けられている App を管理するには、ダッシュボードにアクセスできます。詳しくは、developer portal に関するドキュメントページをご覧ください。ダッシュボードでは、開発者が次の作業を迅速かつ容易に実行できます。

• 既存の Standalone App とそれに関連付けられた App ID を表示します。
• 新しい Project、App、または Standalone App を作成します。
• 未使用の Project または App を削除します。
• 特定の App の設定を確認または更新します（名前、説明、ウェブサイト、コールバック URL、permissions の更新を含む）。
• API Key & Secret、App Access Token、App 所有者のユーザー Access Tokens など、App 固有の認証情報を再生成します。

​

アクセスの申し込み

既存の X App がある場合、developer.x.com で X アカウントにログインしていれば、X のApp ダッシュボードから App を表示・編集できます。なお、developer.x.com 上で以前に作成されたすべての App を管理するために、新たにアカウント登録を行う必要はありません。

新しい X App を作成する場合は、デベロッパーアカウントに登録している必要があります。チームアカウントのメンバーである場合は、新しい App を作成するために管理者ロールが割り当てられている必要があります。

​

ボット向けの自動アカウントのラベル付け

X 上のユーザーに、あなたのボットが自動アカウントであることを知らせるために、ボットアカウントに Automated Account ラベルを付与できます。これらのボットは X API を通じてプログラムされたアクションを実行します。ボットに Automated Account ラベルを追加すると、オーディエンスとの信頼を築き、アカウントの正当性を示し、スパム的なボットと差別化できます。これにより、X 上の人々はボットとやり取りする際に、あなたのアカウントの目的をより理解しやすくなります。

ボットアカウントにラベルを付与するには、次の手順に従ってください:

1. アカウント設定に移動します
2. “Your account” を選択します
3. “Automation” を選択します
4. “Managing account” を選択します
5. 次に、ボットアカウントを運用している X アカウントを選択します
6. パスワードを入力してログインします
7. 最後に、ラベルがアカウントに適用されたことを示す確認メッセージが表示されます。

---

​

Appの管理

​

はじめに

X App ダッシュボードでは、開発者が次の作業を迅速かつ容易に行えます。

• 既存の App とProjects、およびそれらに関連付けられた App の id を表示します。
• 新しい Project またはスタンドアロンの App を作成します。
• Project、App、またはスタンドアロンの App を削除します。
• 特定の App の設定をクリックして開きます。設定では、App の詳細、キーおよびトークン、権限を確認できます。
• App のユーザー認証設定を更新し、OAuth 1.0a または OAuth 2.0 を使用するように構成します。

注:

すべての App のキーおよびトークンは developer portal 内では表示できなくなっており、生成後は必ず安全に保存する必要があります。キーおよびトークンの保管にはパスワードマネージャーの使用を推奨します。

API Key のヒントを表示して、認証情報と対応する App を照合する際の手がかりにできます。

​

App の設定

​

App の詳細

ここでは、App アイコン、App 名、App の説明、自社サイトの URL、callback URLs/redirect URIs、利用規約の URL、プライバシーポリシーの URL、組織名、組織の URL、そして App の目的またはユースケースを編集できます。

OAuth 2.0 と OAuth 1.0a は、ユーザーが X を使ってあなたの App にサインインできるようにする認証方式です。これらを利用すると、認証済みユーザーに代わってあなたの App が特定のリクエストを実行することも可能になります。あなたの App では、いずれか一方、または両方の方式を有効化できます。

この情報を常に最新に保つことが重要です。あなたの App 名とウェブサイトの URL は、あなたのアプリケーションによってプログラム的に作成された Tweets の metadata 内でソースとして表示されます。X App のユースケースを変更する場合は、Developer Terms に準拠するため、必ずこれらの設定でユースケースを更新してください。

あなたのアプリケーションに「suspended」と表示されているタグがある場合、これはアプリが X のdeveloper terms（たとえば当社のautomation rules）のいずれかに違反しているためです。Developer Platform のポリシーチームは、App 所有者の X アカウントに設定されているメールアドレスを通じて開発者に連絡します。このメールアドレスを確認するには、X account settings をご確認ください。アカウント停止に関する通知メールは、このメールアドレスに「Application suspension notice」に類似したタイトルで送信され、次に何をすべきかの具体的な情報が記載されています。停止への対応について X チームと連携するには、具体的な手順についてメールを確認するか、platform help form をご利用ください。

​

キーおよびトークン

Project 内の App、またはスタンドアロンの App から、以下のトークンを表示、再生成、または失効させることができます。

• API Key (Consumer Key) と API Secret (Consumer Secret)
• App Access Token
• User Access Token と Access Token Secret - developer portal で利用可能な Access Token と Secret は、その App の所有ユーザーに紐づいています。

ご注意 - 別のユーザー（つまり App の所有者ではないユーザー）の代わりにリクエストを行う場合は、OAuth 1.0a の 3-legged OAuth フロー か、OAuth 2.0 の Authorization Code with PKCE フロー を使用して、ユーザー用の Access Tokens を発行する必要があります。その後、これらのユーザー固有のトークンを API へのリクエストで使用します。

​

ユーザー認証設定

App の認証設定として OAuth 1.0a または OAuth 2.0 を選択できます。OAuth 2.0 は X API v2 でのみ利用できます。OAuth 2.0 では、ユーザーに代わって特定の権限を付与するきめ細かなスコープを選択できます。OAuth 1.0a は X API v1.1 および v2 で利用でき、より広範な認可と粗いスコープを用います。

​

OAuth 1.0a アプリケーション—ユーザー権限

あなたが App の所有者である場合、App の権限（読み取り専用、読み取りと書き込み、または読み取り・書き込み・ダイレクトメッセージ）を調整できます。これは、X API を通じてアクセスできるリソースおよびイベントを制御します（注: 一部のリソースは X からの追加の許可が必要です）。

このページでは、App がユーザーのメールアドレスの取得を求める機能をオン/オフで切り替えることもできます（この機能を有効にするには、「App details」ページに Terms of Service の URL と Privacy Policy の URL を設定しておく必要があります）。

​

OAuth 2.0 の App の種類

ユーザー認証方法として OAuth 2.0 を選択する場合、作成する App の種類を選択する必要があります。選択肢は Native App、Single page App、Web App、Automated App または bot です。Native App と Single page App はパブリッククライアント、Web App と Automated App または bot は機密クライアントです。

機密クライアントは認可サーバーに対して安全に認証し、クライアントシークレットを安全に保管します。パブリッククライアントは通常、ブラウザやモバイルデバイス上で動作するアプリケーションで、クライアントシークレットを利用できません。機密クライアントに該当する App の種類を選択した場合は、クライアントシークレットが付与されます。

---

​

App の権限

​

OAuth 1.0a App の権限

App の権限は、OAuth 1.0a によるアプリケーション—ユーザー認証のアクセスレベルを示します。App の権限は、X App の設定でアプリケーションごとに構成します。

利用可能な権限レベルは 3 つです:

1. 読み取りのみ
2. 読み取りと書き込み
3. 読み取り、書き込み、ダイレクトメッセージへのアクセス

追加の権限として、ユーザーのメールアドレスの表示を許可するものがあり、上記のいずれのレベルとも組み合わせ可能です。

権限レベルを変更した場合、すでにその X App に発行済みのユーザートークンは破棄し、更新後の権限をトークンに反映させるために、ユーザーは App を再承認する必要があります。

ベストプラクティスとして、アプリケーションやサービスが必要とするユーザーアカウントデータへのアクセスは、必要最小限の権限のみを要求してください。

​

読み取り専用

この権限レベルでは、ユーザーのTweet、ホームタイムライン、プロフィール情報などを含むXのリソースに対して読み取りアクセスが許可されます。ユーザーのダイレクトメッセージの読み取りは許可されず、いかなる要素やオブジェクトの更新も行えません。

​

読み取りと書き込み

この権限レベルでは、X のリソースに対する読み取りおよび書き込みアクセスが許可されます。読み取りアクセスに加えて、Tweet の投稿、ユーザーのフォロー、ユーザーのプロフィール情報の要素の更新が可能です。また、認証済みユーザーに代わって返信を非表示にすることもできます。この権限レベルでは、ダイレクトメッセージ（読み取り・書き込み・DELETE を含む）へのアクセスは一切許可されません。

​

ダイレクトメッセージの読み取り、書き込み、削除へのアクセス

この権限レベルには上記すべてへのアクセスに加え、ユーザーに代わってダイレクトメッセージを読み取り、作成（送信）、削除する機能が含まれます。

• POST /2/dm_conversations/:dm_conversation_id/messages
• POST /2/dm_conversations/
• POST /2/dm_conversations/with/:participant_id/messages
• GET /2/dm_conversations/with/:user_id/dm_events
• GET /2/dm_conversations/:dm_conversation_id/dm_events
• GET /2/dm_events

​

権限の判定

認証済みの API リクエストはすべて、HTTP レスポンスに x-access-level ヘッダーを含めて返します。ヘッダーの値は、現在適用されている権限レベルを示します。取り得る値は read、read-write、read-write-directmessages です。

---

​

コールバックURL

OAuth 1.0a ユーザーコンテキストと OAuth 2.0 Authorization Code（PKCE 付き）の認証方式を利用すると、特定のサインインフローを完了した別の X ユーザーに代わって、開発者がリクエストを実行できるようになります。現在、ユーザーにアプリケーションの認可を与えてもらうために使用できるフローは次の2つです。

• OAuth 2.0 authorization code flow with PKCE
• OAuth 1.0a 3-legged OAuth flow（および別途、Sign in with X flow）

ユーザーがこれらのフローを進める際には、ログインに成功し、開発者の App への認可を付与した後に遷移するためのウェブページまたは場所が必要です。この遷移先のウェブページまたは場所はコールバックURLと呼ばれます。

これらのフローを利用できるよう設定する際、開発者は前述のフローを構成する認証 endpoint へのリクエストに、コールバックURLを渡す必要があります。たとえば、OAuth 1.0a ユーザーコンテキストを使用する開発者は、GET oauth/request_token endpoint にリクエストする際に callback_url パラメータを渡す必要があります。同様に、OAuth 2.0 Authorization Code（PKCE 付き）を使用する場合は、GET oauth2/authorize endpoint へのリクエストに redirect_uri パラメータを渡す必要があります。

これらのパラメータを指定するだけでなく、コールバックURLが App のコールバックURL許可リストにも追加されていることを確認してください。これは developer portal の App 設定ページで確認できます。

正しく設定されていれば、これらのフローの一環として X へのサインインに成功した後、ユーザーはコールバックURLにリダイレクトされます。

​

留意すべき点

コールバックURLを設定する際は、次の点に留意してください。

query パラメータを HTTP エンコードする

callback_url または redirect_uri パラメータでコールバックURLを query パラメータとして渡すため、URL を HTTP エンコードしてください。

コールバックURLの制限

X Apps ダッシュボードでは、コールバックURLは最大 10 件までという厳格な上限があります。コールバックURLは、Apps ダッシュボードで許可リストに追加したコールバックURLと、認可フローで指定するパラメータの値が常に完全一致している必要があります。

コールバックURLにリクエスト固有のデータを含めたい場合は、state パラメータを使用して、ユーザーがリダイレクトされた後に受け渡されるデータを保持できます。state パラメータ自体にデータをエンコードするか、サーバー側で状態を保持するためのセッションIDとしてこのパラメータを使用できます。

localhost をコールバックURLとして使用しないでください localhost の代わりに、ローカルではカスタムホスト、または http(s)://127.0.0.1 を使用してください。

カスタムプロトコルURL モバイルのディープリンクを活用する場合は、twitter://callback/path のように、パスとドメイン部分を含むカスタムプロトコルURLを利用できます。ただし、利用禁止のプロトコル一覧があるため、これらは避けてください。以下で禁止プロトコルの一覧を確認できます。

禁止プロトコル

vbscript	ldap
javascript	mailto
vbs	mmst
data	mmsu
mocha	msbd
keyword	rtsp
livescript	mso-offdap
ftp	snews
file	news
gopher	nntp
acrobat	outlook
callto	stssync
daap	rlogin
itpc	telnet
itms	tn3270
firefoxurl	shell
hcp	sip

​

エラーの例

developer portal の App 設定にコールバック URL が正しく追加されていない場合、次のエラーメッセージが表示されます。

OAuth 1.0a

HTTP 403 - Forbidden

{
  "errors": [
    {
      "code":415,"message":"このクライアントアプリケーションではコールバックURLが承認されていません。承認済みコールバックURLはアプリケーション設定で調整できます。"
    }
  ]
}

または

<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>このクライアントアプリケーションではコールバックURLが承認されていません。承認されたコールバックURLはアプリケーション設定で調整できます</error>
<request>/oauth/request_token</request>
</hash>

OAuth 2.0

HTTP 400

{
  "error": "invalid_request",
  "error_description": "リダイレクトURIに渡された値が認証コードのURIと一致しませんでした。"
}

トラブルシューティング

エラーが発生した場合は、認証リクエストで使用しているコールバックURLがHTTPエンコードされていること、またリクエストで使用しているAppのキーおよびトークンに紐づく許可リストに登録されたコールバックURLと一致していることを確認してください。

---