Crewcade API
Crewcade API で、自分のウェブサイトやアプリをクラブとつなげます。画面はあなたが作ります。メンバーの管理は Crewcade が担います。
今できること
Section titled “今できること”Crewcade で作ったキーを使い、あなたのサーバーからクラブのメンバーとイベントを読み取ります。あなたのウェブサイトやアプリで、メンバーが Crewcade アカウントでサインインすることもできます。サインイン後、メンバーが許可した名前、写真、メールアドレスをアプリが読み取れます。アプリは、そのメンバーが見られるイベントも読めます。権限を足すと、メンバーを無料のイベントに申し込ませたり、イベントに参加する人を表示したりできます。Crewcade でサインインと連携アプリを見てください。
クラブで何かが変わったときに、サーバーでメッセージを受け取ることもできます。これが Webhook です。Webhookを見てください。
クイックスタート
Section titled “クイックスタート”- Crewcade で 設定 を開き、開発者 を選びます。APIキー タブを開きます。メンバー閲覧 権限でキーを作ります。
- キーをコピーします。キーは
cck_で始まります。 - 自分のパソコンで次を実行します。
curl https://api.crewcade.com/api/v1/members \ -H "Authorization: Bearer cck_your_key_here"クラブのメンバーが最初の 20 人分返ってきます。
リクエストはすべて次のベース URL に送ります。
https://api.crewcade.com/api/v1キーを作れるのは、連携管理 権限を持つ人です。オーナーと管理者は最初から持っています。
- 設定 を開き、開発者 を選びます。APIキー タブを開きます。
- APIキーを作成 を押します。名前、権限、有効期限を決めます。
- キーをコピーします。キーは
cck_で始まります。
キーが表示されるのは一度だけです。安全な場所に保管してください。なくした場合は、そのキーを無効にして新しく作ります。キーが作られるたびに、クラブのオーナーにメールが届きます。
キーはサーバーだけに置きます。ウェブページや携帯アプリに入れたキーは公開されたのと同じです。見つけた人は誰でも使えてしまいます。
キーを Authorization ヘッダーに入れて送ります。
curl https://api.crewcade.com/api/v1/key \ -H "Authorization: Bearer cck_your_key_here"返事には、このキーでできることが表示されます。
{ "keyId": "key_123", "workspaceId": "k3m9x2pq4r7t", "permissions": ["can_view_members"]}権限はキーを作るときに選びます。選べるのは、自分が持っている権限だけです。
| 権限 | Crewcade での名前 | できること |
|---|---|---|
can_view_members | メンバー閲覧 | メンバーを読む |
can_view_sensitive_member_data | 機微なメンバー情報の閲覧 | 機微な項目の回答も読む。読み取りはすべて記録されます。 |
can_view_all_events | すべてのイベントを表示 | 非表示のものも含めてイベントを読む。下書きは含みません。 |
can_check_in_attendees | 参加者チェックイン | イベントの参加者を読む(can_view_all_events と一緒に使います) |
can_manage_webhooks | Webhook管理 | Webhook のエンドポイントを追加、変更、削除する |
新しい権限は、それを使うエンドポイントと一緒に追加されます。
キーは、作った人以上のことはできません。次の場合、キーは使えなくなります。
- 作った人が権限や 連携管理 を失った、またはクラブを退会した。
- キーの有効期限が切れた。
- キーが無効にされた。
有効期限は 30 日、90 日、1 年、無期限から選べます。初期設定は 1 年です。
| ステータス | 意味 |
|---|---|
| 401 | キーが正しくありません。本文は毎回 Invalid API key です。 |
| 403 | キーに権限が足りません。本文に code: "api_key_permission_missing" と missingPermissions の一覧が入ります。 |
| 404 | 求めたものがクラブに存在しません。 |
| 429 | リクエストが多すぎます。本文は rate_limited です。Retry-After ヘッダーの秒数だけ待ってください。 |
1 つのキーで送れるのは、1 分あたり 60 リクエストです。正しいキーへの返事には、次のヘッダーが付きます。
RateLimit-Limitは上限です。RateLimit-Remainingは残りのリクエスト数です。RateLimit-Resetはカウントが戻るまでの時間です。
同じ IP アドレスから 1 分間にキーの認証に 10 回失敗すると、その分が終わるまでそのアドレスはブロックされます。
エンドポイント
Section titled “エンドポイント”| メソッドとパス | 権限 | ページ |
|---|---|---|
GET /key | どのキーでも可 | このページ |
GET /members | can_view_members | メンバー |
GET /members/{memberId} | can_view_members | メンバー |
GET /events | can_view_all_events | イベント |
GET /events/{id} | can_view_all_events | イベント |
GET /events/{id}/registrations | can_view_all_events、can_check_in_attendees | イベント |
GET /events と GET /events/{id} | メンバートークン(追加のスコープは不要) | イベント |
GET /me/registrations | registrations のメンバートークン | 申し込み |
GET、POST、DELETE /events/{id}/registration | registrations のメンバートークン | 申し込み |
GET /events/{id}/people | people のメンバートークン | 出会う人 |
GET /me | メンバートークン | 自分とクラブ |
GET /workspace | 任意のキーまたはメンバートークン | 自分とクラブ |
/webhook-endpoints とそのサブパス | can_manage_webhooks | Webhook |
GET /me と GET /workspace は、Crewcade でサインインで得たメンバートークンでも使えます。メンバーのエンドポイントと GET /events/{id}/registrations には APIキー が必要です。イベントのエンドポイントは、どのメンバートークンでも使えます。
どの /v1 リクエストにも ?locale=ja を付けると、言語を選べます。Accept-Language ヘッダーでも選べます。両方送った場合は locale が優先されます。自分とクラブを見てください。
OpenAPI 仕様
Section titled “OpenAPI 仕様”機械で読める仕様ファイルはここにあります。
https://docs.crewcade.com/openapi/v1.jsonOpenAPI 3.0 形式で、API のコードから作られています。上のエンドポイント、項目、エラーがすべて入っています。次のように使えます。
- Postman、Insomnia、Bruno で各リクエストを試す。
- OpenAPI Generator などのツールで、自分の言語の型付きクライアントを作る。
- AI コーディングツールに、返事の正確な形を渡す。