組織 · Ephemeral ドキュメント

ホスト型サービスでは、組織、メンバー、API キー、クレジット、デプロイメントのライセンスを、https://ephemer.al/v1 の組織 API で管理します。カスタマーポータルとダッシュボードは、この API を代わりに呼び出します。このページは、スクリプトやインテグレーション向けです。

認証

これらのエンドポイントは、人として操作します。POST /v1/auth/login でログインし、返された token を Bearer トークンとして送信してください。セッションの有効期間は 30 日です。POST /v1/auth/logout で、期限前に終了できます。

ターミナル

curl https://ephemer.al/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"…"}'

レスポンスは {"token": "...", "user": {...}, "organizations": [...]} です。各組織には、id、name、あなたの role が含まれます。以下のエンドポイントは、組織の一覧と作成、および招待の承諾を除き、パスで指定した組織でのオーナーまたは管理者のロールが必要です。

ここでは API キーは使えません

管理者キーを含む組織の API キーでは、メンバー、キー、請求、ライセンスのエンドポイントを呼び出せません。これにより、キーが漏えいしても、人の追加、キーの発行、支出はできません。キーは、自分の組織の残高を読み取ることはできます。

組織

GET/v1/organizations

所属している組織を、id、name、role とともに一覧します。

POST/v1/organizations

{"name": "..."} から組織を作成し、あなたをオーナーにします。201 と {"id": "org_...", "name": "...", "role": "owner"} を返します。

PATCH/v1/organizations/{id}

オーナーまたは管理者。{"name": "..."} で組織名を変更します。名前は前後の空白が除かれ、1〜200 文字である必要があります。{"id": "org_...", "name": "...", "role": "owner"} を返します。メンバーには 403 を返します。

メンバー

GET/v1/organizations/{id}/members

メンバーを、id、email、name、role、avatar_url とともに一覧します。

DELETE/v1/organizations/{id}/members/{user_id}

メンバーを削除します。管理者はメンバーを削除でき、管理者を削除できるのはオーナーだけです。オーナーは削除できません。

PATCH/v1/organizations/{id}/members/{user_id}

オーナーのみ。{"role": "admin"} または {"role": "member"} で、メンバーのロールを変更します。

POST/v1/organizations/{id}/ownership

オーナーのみ。{"user_id": "..."} で、既存のメンバーにオーナー権限を移譲します。あなたは管理者になります。

招待

POST/v1/organizations/{id}/invitations

{"email": "...", "role": "member"} で、ユーザーを招待します。role は admin または member です。201 と、token、url、email_delivery を返します。

email_delivery は、メールプロバイダーがメッセージを受け付けた場合に accepted になります。これは、受信トレイに届いたことを保証するものではありません。unavailable または failed の場合は、返された url を非公開の方法で共有してください。招待の有効期限は 7 日です。招待された人は、招待先のメールアドレスでログインした状態で、POST /v1/invitations/accept と {"token": "..."} を使って承諾します。

API キー

GET/v1/organizations/{id}/keys

キーを、id、name、role、created_at とともに一覧します。シークレットは一覧に含まれません。

POST/v1/organizations/{id}/keys

{"name": "...", "role": "member"} からキーを作成します。role は member または admin で、デフォルトは member です。

201 Created

{
  "id": "key_0b7e4c2a9d1f8356e4a2c7b9d0f1e3a5",
  "name": "production-server",
  "role": "member",
  "key": "eak_…"
}

key の値が返されるのは 1 度だけです。レスポンスを閉じる前に保管してください。

DELETE/v1/organizations/{id}/keys/{key_id}

キーをただちに失効させます。

プロフィール

これらには、ユーザーとしてのログインセッションが必要です。API キーは拒否されます。ユーザーと、members の各エントリには avatar_url があります。/v1/users/usr_…/avatar?v=3f2a… のようなパス、または null です。

PUT/v1/me/avatar

ボディには、Content-Type が image/png、image/jpeg、image/webp のいずれかである生の画像を、256 KiB まで指定します。GET /v1/auth/me と同じボディを返します。アップロードは 1 時間に 20 回までです。

DELETE/v1/me/avatar

画像を削除します。

POST/v1/me/password

{"current_password": "...", "new_password": "..."} でパスワードを変更します。新しいパスワードは 12 から 72 バイトです。ほかのセッションはログアウトされ、リクエストを送ったセッションはログインしたままです。試行は 1 時間に 10 回までです。

GET/v1/users/{user_id}/avatar

そのユーザーと、同じ組織に所属する人に対して、画像を返します。それ以外の人には 404 を返します。画像が変わると URL も変わるため、ずっとキャッシュできます。

請求

これらのエンドポイントでは、Stripe の金額にはセント、ウォレットの金額にはマイクロを使います。予算と請求をご覧ください。

GET/v1/organizations/{id}/balance

メンバー、またはその組織の API キーで利用できます。{"balance_micros": ..., "reserved_micros": ..., "available_micros": ...} を返します。それぞれ、保有しているクレジット、未精算の実行のために確保されているクレジット、新しい実行で使えるクレジットです。実行を開始する前に、available_micros を実行の予算と照らし合わせて確認してください。

GET/v1/organizations/{id}/billing

ウォレットと支払いの設定を返します。

balance_micros, reserved_micros, available_microsinteger

保有しているクレジット、未精算の実行のために確保されているクレジット、新しい実行で使えるクレジット。

ledgerarray

最新 100 件のエントリ。各エントリには amount_micros、description、created_at が含まれ、該当する場合は run_id、payment_id、topup_id も含まれます。

purchase_limitsobject

min_amount_cents、max_amount_cents、min_threshold_cents。上限値をコードに固定せず、これらに照らして検証してください。

auto_topupobject

enabled、threshold_cents、amount_cents、payment_method_saved、last_topup_status。

payment_methodobject | null

チャージに使うカード。brand、last4、exp_month、exp_year、source。

payment_method_syncstring

synced。Stripe に接続できなかった場合は unavailable。取得に失敗しても、カードがないとは限りません。

stripe_configuredboolean

支払いが利用できるかどうか。

POST/v1/organizations/{id}/billing/checkout

{"amount_cents": 2500} でクレジットの購入を開始し、Stripe Checkout の {"url": "..."} を返します。自動チャージ用にカードを保存するには、"save_payment_method": true を追加します。金額は 500 から 1,000,000 セントです。

POST/v1/organizations/{id}/billing/portal

カードを管理する Stripe カスタマーポータルの {"url": "..."} を返します。

PUT/v1/organizations/{id}/billing/auto-topup

{"enabled": true, "threshold_cents": 1000, "amount_cents": 5000, "consent": true} で自動チャージをオンに、{"enabled": false} でオフにします。オンにするには、保存済みのカードが必要です。

GET/v1/organizations/{id}/billing/payments

支払い履歴を新しい順に返します。limit (1 から 100、デフォルトは 25) と cursor を指定でき、{"payments": [...], "next_cursor": "..."} を返します。各支払いには、amount_cents、 refunded_cents、disputed_cents、refund_status、created_at、topup_id、receipt_endpoint が含まれます。

GET/v1/organizations/{id}/billing/payments/{payment_id}/receipt

Stripe の領収書の {"url": "..."} を返します。Stripe から領収書が提供されていない場合は 404 を返します。

デプロイメントのライセンス

GET/v1/organizations/{id}/license

組織のセルフホストの利用権 (entitlement)、または {"entitlement": null}。

GET/v1/organizations/{id}/deployments

登録済みのインストールを一覧します。

POST/v1/organizations/{id}/deployments

{"name": "..."} でインストールを登録し、そのライセンストークンを、Ephemeral が生成したマシン ID (または送信した machine_id) とともに 1 度だけ返します。

DELETE/v1/organizations/{id}/deployments/{deployment_id}

インストールを無効化します。

これらのフィールドと、インストールがトークンを使う方法については、デプロイメントのライセンスで説明しています。