API キーを使うと、開発者やあなたが運用するツールが Mateflow の Open API でコミュニティのデータを読み書きできます。API キーの作成、置き換え、無効化は、管理画面 → 設定 → 連携 → API アクセスで行います。各キーは 1 つのコミュニティでのみ使えます。
対象者:オーナーと管理者。 · 場所:ウェブ(管理画面)。 · プラン:API アクセスと、コミュニティが 1 日に送れる API リクエスト数は、プラットフォームプランによって異なります。
API キーはコミュニティごとに作成する
API キーは 1 つのコミュニティに属し、キーを使ったリクエストは常にそのコミュニティに対して実行されます。複数のコミュニティを接続するには、それぞれのコミュニティの管理画面でキーを作成します。
クリエイターダッシュボード(app.mateflow.com)には API キーはありません。以前そこにあったワークスペース単位のキーは、コミュニティごとのキーに置き換えられました。クリエイターダッシュボードのコミュニティの概要ページには、そのコミュニティの連携ページへのリンクがあります。
API キーを作成する手順
- 管理画面 → 設定 → 連携に移動し、API アクセスタブを開きます。
- 新しいキーを生成をクリックします。
- 使うツールの名前とそのツールが行うことなど、用途がわかるキー名を入力します。有効期限のリマインダーにはキー名が表示されるため、わかりやすい名前にしておくと、どの連携についてのリマインダーかがわかります。
- 任意:公開コンテンツのみをオンにします。たとえば、公開コンテンツを表示するために第三者へキーを渡す場合です。後述のキーを公開コンテンツに限定するを参照してください。
- スコープと権限で、連携に必要な権限だけにチェックを入れます。次のセクションを参照してください。
- 有効期限で、無期限のままにするか、30 日、90 日、180 日、365 日のいずれかを選びます。フォームには、キーが使えなくなる正確な日時が表示されます。
- 任意:IP ホワイトリスト(任意) に、キーの使用を許可する IP アドレスまたは範囲をカンマ区切りで入力します。
- 新しいキーを生成をクリックします。
- API キーが生成されましたからキーをコピーして安全な場所に保管し、完了をクリックします。
キー全体を確認できるのは一度だけです。紛失した場合は、代わりのキーを作成し、古いキーを無効化してください。
キーの権限、有効期限、公開コンテンツのみの設定は、作成後に変更できません。変更するには、代わりのキーを作成します(後述)。
API アクセスタブにアップグレードの案内が表示される場合は、プラットフォームプランに API アクセスが含まれていません。API エンドポイントカードには、リクエストのベース URL と、プランの 1 日あたりのリクエスト数の上限が表示されます。上限は 00:00 UTC にリセットされます。
API キーのスコープ(権限)
権限は、データの種類ごとに 1 行ずつ並び、操作ごとにチェックボックスがあります。各チェックボックスが 1 つのスコープに対応します。
| 行 | チェックボックス | 許可される操作 |
|---|---|---|
| コミュニティ | 読み取り | コミュニティのプロフィール、設定、メタデータを読み取ります |
| コンテンツ | 読み取り | 投稿、フィード、返信、検索結果を読み取ります |
| コンテンツ | 書き込み | 投稿と返信を作成、編集、削除します |
| メディア | 読み取り | 既存のメディアの署名付き URL を読み取ります |
| メディア | アップロード | アップロードトークンを要求します。署名付きメディア URL の読み取りも含みます |
| スペース | 読み取り | スペースを一覧表示し、スペースの詳細を読み取ります |
| メンバー | 読み取り | メンバーを検索し、アクセスグループを含む基本的なプロフィールを読み取ります |
| メンバー | 招待 | メールアドレスまたは招待リンクで人を招待します |
フォームを開いた時点で、コミュニティの読み取りにはチェックが入っています。書き込みやアップロードにチェックを入れても、読み取りに自動でチェックが入ることはありません。投稿を作成するだけのツールなら、コンテンツの書き込みだけで足ります。
メンバーの行は、機微な権限の下に表示されます。読み取りを使うと、連携はメールアドレスがコミュニティのメンバーのものかどうかを確認できます。招待では、連携が別の招待者を指定しない限り、招待はコミュニティのオーナーとして送信されます。招待された人は、常にメンバーとして参加します。API による招待にはアクセスグループを含めることができます。アクセスグループの仕組みを参照してください。
古いキーにはすべて(旧仕様) と表示されることがあります。このキーには、作成時に存在していたスコープだけが付いています。新しいスコープを使うには、新しいキーを作成してください。
キーを公開コンテンツに限定する
公開コンテンツのみをオンにすると、キーで見えるのは、ログインしていない訪問者に見える内容だけになります。これには非公開スペースの名前と説明が含まれますが、シークレットスペースのものは含まれません。第三者に渡すキーや、公開コンテンツを表示するだけのツールに使ってください。
オフの場合、キーは連携が指定した任意のメンバーとして読み取れます。管理者を指定すれば、非公開スペースや有料スペースも読み取れます。読み取りだけにチェックを入れたキーでも同じなので、読み取り専用は公開コンテンツのみという意味ではありません。
このキーに付与できるのは、コミュニティ、コンテンツ、スペースの読み取りだけです。オンにすると、ほかのチェックボックスはチェックが外れ、選択できなくなります。メンバーを指定したリクエストは拒否されます。API キーの一覧では、このキーに公開のみのラベルが表示されます。既存のキーには影響しません。
API キーの有効期限が切れたとき
有効期限を設定したキーは、作成時に表示された日時に使えなくなります。その後もそのキーを使ったリクエストは、拒否されます。返されるエラーから、開発者はキーが無効化されたのでも入力を間違えたのでもなく、有効期限が切れたことがわかります。
API キーの一覧のステータス列には、残り 62 日で失効のようにカウントダウンが表示され、最終日は時間単位になります。残りが 14 日以下になると、カウントダウンが警告色に変わります。カーソルを合わせると、正確な日時が表示されます。期限が切れたキーのステータスは期限切れになります。
オーナーと管理者には、キーの有効期限の 14 日前、1 日前、期限が切れたときにリマインダーが届きます。各リマインダーは通知とメールの両方で届き、キーが最後に使われた日時が記載されているため、まだそのキーを使っているものがあるかどうかを判断できます。通知をクリックすると、そのキーが強調表示された状態で API アクセスが開きます。Mateflow アプリでは、通知に同じ詳細が表示されますが、タップしても何も開きません。メールはすぐに送信されます。通知設定でメール通知をオフにしている場合や、メールを毎日または毎週のダイジェストで受け取っている場合も同じです。メールで届かないのは、システム通知のメールをオフにしている場合か、通知のまとめメール(以前のメールダイジェスト頻度)をオフにしている場合だけです。無効化したキーのリマインダーは届きません。
有効期限は延長できません。連携を止めずに使い続けるには、有効期限が切れる前にキーを置き換えてください。
API キーを置き換える
置き換えると、同じ設定の新しいキーが作成されます。キーは複数同時に持てるため、連携を止めずに切り替えられます。有効期限のないキーに有効期限を付けるときも、この方法を使います。
- API アクセスタブで、キーの操作メニューを開き、代わりのキーを作成をクリックします。残りが 14 日以下のキーや期限切れのキーでは、その行に置き換えボタンも表示されます。
- 古いキーの名前、権限、公開コンテンツのみの設定、IP ホワイトリスト、有効期限が入力された状態で、代わりのキーを作成が開きます。必要な項目を変更し、新しいキーを生成をクリックします。このフォームでは付与できない権限が古いキーにある場合は、「引き継げなかった権限」の注記にその権限が表示され、新しいキーにはその権限が付きません。
- 新しいキーをコピーし、連携に設定します。
- 連携が新しいキーを使い始め、新しいキーに最終使用の時刻が表示されたら、次のステップ: 古いキーを無効化の下にある古いキーを無効化をクリックして確認します。あとで一覧から古いキーを無効化してもかまいません。無効化するまでは、古いキーにも有効期限のリマインダーが届きます。
2 つのキーは同じ名前になります。名前の下に表示されるキーのプレフィックスと、作成日で見分けてください。
API キーを無効化する
- API アクセスタブの API キーで、対象のキーを見つけます。
- キーの操作メニューを開き、キーを無効化をクリックします。
- 確認します。無効化は元に戻せず、そのキーを使っているツールは動作しなくなります。
一覧には、各キーのステータス(有効、期限切れ、失効済み)と最終使用日が表示されます。API リクエストは配信ログに表示されないため、キーがまだ使われているかどうかは最終使用で確認します。Slack、Discord、Zapier の接続を切断しても、API キーは無効化されません。キーの作成と無効化は、管理画面 → 設定 → 監査ログのインテグレーションに記録されます。
API キーを安全に管理する
- API キーは、他の人がダウンロードできるウェブサイトやアプリではなく、サーバーに保管し、リクエストは HTTPS で送ってください。
- ツールごとに、必要なスコープだけを持つ個別のキーを用意します。そうすれば、1 つを無効化してもほかのツールに影響しません。
- 公開コンテンツを表示するだけのキーでは、公開コンテンツのみをオンにします。第三者に渡すキーでは特にそうしてください。
- 有効期限を設定し、定期的にキーを置き換えます。そうすれば、気づかないうちに漏洩したキーも自動的に使えなくなります。
- ツールが固定のアドレスから呼び出す場合は、IP ホワイトリストを追加します。
- キーが漏洩した可能性がある場合は、すぐに無効化し、代わりのキーを作成してください。
API ドキュメントの場所
API リファレンスでは、エンドポイント、リクエストとレスポンスの形式、スコープ、エラーコード、コードサンプルを説明しています。API アクセスタブの開発者向けドキュメントカードにあるドキュメントを開くボタンから、mateflow.com/developers に移動できます。このリンクを開発者に送ってください。開発者はコミュニティのアカウントを持っている必要はなく、プランに API アクセスが含まれていなくてもこのページを利用できます。
関連記事
このガイドは役に立ちましたか?