既存のアプリがある場合は、開発者ポータルのアプリページで表示、編集、削除できます。
X API および X Ads API へアクセスするには、各リクエストに添える必要がある、キーやトークンとも呼ばれる一連の認証用クレデンシャルが必要です。これらのクレデンシャルは、使用する特定のエンドポイントで求められる認証方式に応じて形式が異なります。
アプリで生成できる各種クレデンシャルとその用途は次のとおりです。
-
API Key と Secret： いわばアプリのユーザー名とパスワードです。OAuth 1.0a ユーザーコンテキストを要するリクエストの認証や、ユーザー Access Token や App Access Token など他のトークンの生成に使用します。
-
Access Token と Secret： 一般に、Access Token は代理でリクエストを行う対象ユーザーを表します。開発者ポータルで生成できるものは、アプリの所有者であるユーザーを表します。OAuth 1.0a ユーザーコンテキストを要するリクエストの認証に使用します。別のユーザーの代理でリクエストする場合は、そのユーザーに承認してもらうために 3-legged OAuth フローを使用する必要があります。
-
Client ID と Client Secret： これらのクレデンシャルは、OAuth 2.0 認証でユーザー Access Token を取得するために使用します。OAuth 1.0a と同様に、ユーザー Access Token は非公開のユーザーアカウント情報を提供するリクエストや、他アカウントの代理で操作を行うリクエストの認証に使用されますが、クライアントアプリケーションがユーザーに対して持つアクセス権限を、より細かいスコープで制御できます。
-
App only Access Token： X 上で一般公開されている情報を返すエンドポイントへのリクエストに使用します。
X API リクエストに必要なキーやトークンを生成できるほか、権限の設定、アプリのユースケースや目的の記載、コールバック URLの定義、さらに管理ダッシュボードからアプリの開発者環境に関連するその他の設定も変更できます。
ユースケースごとに作業を整理するために、X Developer Platform ではアプリとプロジェクトを利用できます。各プロジェクトには、無料の X API プランではアプリを1つ、ベーシックプランでは最大2つ、プロプランでは最大3つまで含めることができます。
新しい X API v2 のエンドポイントにアクセスするには、プロジェクトに関連付けられたアプリのキーとトークンを使用する必要があります。
プロジェクトの導入前に作成されたアプリがある場合は、「単体アプリ」というセクションに表示されます。単体アプリは、プロジェクト構造の外にあるアプリです。単体アプリをプロジェクトに関連付けると、v2 エンドポイントへのリクエストが可能になります。
アカウントに関連付けられているアプリを管理するには、ダッシュボードにアクセスしてください。詳しくは、開発者ポータルに関するドキュメントをご覧ください。ダッシュボードでは、開発者が次の作業を迅速かつ簡単に実行できます。
- 既存の単体アプリと、それに関連付けられた App id を表示する。
- 新しいプロジェクト、アプリ、または単体アプリを作成する。
- 未使用のプロジェクトまたはアプリを削除する。
- 特定のアプリの設定を確認または更新する（名前、説明、ウェブサイト、コールバック URL、権限 など）。
- API Key & Secret、App Access Token、アプリ所有者のユーザー Access Token など、アプリ固有の認証情報を再生成する。
既存のXアプリがある場合、developer.x.comでXアカウントにログインしていれば、XのApp dashboardからアプリを表示・編集できます。なお、以前にdeveloper.x.com上で作成したすべてのアプリを管理するために、新たにアカウント登録を行う必要はありません。
新しいXアプリを作成する場合は、developer accountに登録している必要があります。team accountのメンバーである場合は、新しいアプリを作成するには管理者ロールが割り当てられている必要があります。
X上のユーザーにあなたのボットが自動アカウントであることを知らせるために、ボットアカウントに自動アカウントラベルを追加できます。これらのボットは、X APIを通じてプログラムされたアクションを実行します。ボットに自動アカウントラベルを付与すると、オーディエンスとの信頼が高まり、アカウントの正当性を示し、スパム的なボットとの差別化が図れます。これにより、ユーザーがボットとやり取りする際に、X上であなたのアカウントの目的をより理解しやすくなります。
ボットアカウントにラベルを追加するには、次の手順に従ってください。
- アカウント設定に移動
- 「あなたのアカウント」を選択
- 「自動化」を選択
- 「アカウントの管理」を選択
- 次に、ボットアカウントを運用しているXアカウントを選択
- パスワードを入力してログイン
- 最後に、ラベルがアカウントに適用されたことを確認します。
X アプリのダッシュボードでは、開発者が次の作業を迅速かつ容易に行えます。
- 既存のアプリやプロジェクトと、それらに関連付けられた App ID を表示します。
- 新しいプロジェクトまたは単体アプリを作成します。
- プロジェクト、アプリ、または単体アプリを削除します。
- 特定のアプリの設定を開きます。設定内では、アプリの詳細、キーとトークン、権限を確認できます。
- アプリのユーザー認証設定を更新し、OAuth 1.0a または OAuth 2.0 を使用するようにします。
注:すべてのアプリのキーとトークンは開発者ポータル内では表示できなくなっており、生成時に安全に保存する必要があります。キーとトークンの保管にはパスワードマネージャーの使用を推奨します。API キーのヒントを表示して、認証情報を対応するアプリと照合する際の手がかりにできます。
OAuth 1.0a アプリケーション—ユーザー権限
アプリ権限は、OAuth 1.0a によるアプリケーションとユーザーの認証におけるアクセスレベルを示します。アプリ権限は、X アプリ の設定内でアプリごとに構成します。
利用可能な権限レベルは3つあります:
- 読み取りのみ
- 読み取りと書き込み
- 読み取り、書き込み、ダイレクトメッセージへのアクセス
追加の権限として、ユーザーのメールアドレスの閲覧をリクエストでき、これは上記3つのいずれのレベルとも組み合わせ可能です。
権限レベルを変更した場合、その X アプリにすでに発行されているユーザートークンはすべて無効化し、更新後の権限をトークンに反映させるため、ユーザーはアプリを再承認する必要があります。
ベストプラクティスとして、アプリケーションやサービスが必要とするユーザーアカウントデータへのアクセスは、必要最小限のレベルのみをリクエストしてください。
この権限レベルでは、ユーザーのTweet、ホームタイムライン、プロフィール情報など、X の各種リソースを閲覧できます。ユーザーのダイレクトメッセージを読むことはできず、いかなる要素やオブジェクトの更新も行えません。
この権限レベルでは、X リソースへの読み取りおよび書き込みアクセスが許可されます。読み取りに加えて、Tweet の投稿、ユーザーのフォロー、ユーザーのプロフィール情報の要素の更新が可能です。また、認証済みユーザーに代わって返信を非表示にすることもできます。この権限レベルでは、ダイレクトメッセージ（読み取り・書き込み・削除を含む）へのアクセスは一切許可されません。
この権限レベルには上記すべてへのアクセスに加えて、ユーザーに代わってダイレクトメッセージを閲覧、作成、削除する機能が含まれます。
すべての認証済み API リクエストは、HTTP レスポンスに x-access-level ヘッダーを含めて返します。ヘッダーの値は、現在適用されている権限レベルを示します。取りうる値は read、read-write、read-write-directmessages です。
OAuth 1.0a ユーザーコンテキストと OAuth 2.0 認可コード（PKCE 対応）の認証方法により、特定のサインインフローを経た別々の X ユーザーに代わって、開発者がリクエストを実行できます。現在、ユーザーがあなたのアプリケーションを認可できるフローは次の2つです。
ユーザーがこれらのフローを進める際、X にログインし、開発者のアプリを認可した後に遷移させるウェブページまたは場所が必要です。この遷移先をコールバックURLと呼びます。
これらのフローをユーザー向けに設定する際、開発者は、前述のフローを構成する認証エンドポイントへのリクエストにコールバックURLを渡す必要があります。たとえば、OAuth 1.0a ユーザーコンテキストを使用する開発者は、GET oauth/request_token エンドポイントにリクエストする際に callback_url パラメータを渡す必要があります。同様に、OAuth 2.0 認可コード（PKCE 対応）を使用する開発者は、GET oauth2/authorize エンドポイントへのリクエストに redirect_uri パラメータを渡す必要があります。
これらのパラメータの指定に加えて、コールバックURLが アプリ のコールバックURL許可リストに追加されていることも確認する必要があります。これは 開発者ポータル のアプリ設定ページで確認できます。
適切に設定されていれば、これらのフローの一環として X へのサインインに成功した後、ユーザーはコールバックURLへリダイレクトされます。
コールバックURLを設定する際は、次の点に留意してください。
クエリパラメータはHTTPエンコードする
callback_url または redirect_uri でコールバックURLをクエリパラメータとして渡すため、URLは必ずHTTPエンコードしてください。
コールバックURLの制限
X Apps ダッシュボードでは、コールバックURLは最大10件までのハードリミットがあります。コールバックURLは、Apps ダッシュボードで許可リストに追加したコールバックURLと、認可フローで指定するパラメータの値が常に完全一致している必要があります。
コールバックURLにリクエスト固有のデータを含めたい場合は、ユーザーのリダイレクト後に含めるデータを保持するために state パラメータを使用できます。state パラメータ自体にデータをエンコードするか、このパラメータをセッションIDとして用いてサーバー側に状態を保存することができます。
コールバックURLとして localhost を使用しないでください
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 |
{
"errors": [
{
"code":415,"message":"このクライアントアプリケーションでは、コールバックURLが承認されていません。承認済みコールバックURLは、アプリケーション設定で調整できます。"
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>このクライアントアプリではコールバックURLが承認されていません。承認済みコールバックURLはアプリ設定で調整できます</error>
<request>/oauth/request_token</request>
</hash>
{
"error": "invalid_request",
"error_description": "リダイレクトURIに渡された値が、認証コードのURIと一致しません。"
}
