조직 · Ephemeral 문서

호스팅 서비스에서 조직, 멤버, API 키, 크레딧, 배포 라이선스는 https://ephemer.al/v1의 조직 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 키가 거부됩니다

admin 키를 포함한 조직 API 키는 멤버, 키, 결제, 라이선스 엔드포인트를 호출할 수 없습니다. 이렇게 해서 유출된 키로 사람을 추가하거나, 키를 발급하거나, 비용을 지출하는 일을 막습니다. 키는 자기 조직의 잔액은 읽을 수 있습니다.

조직

GET/v1/organizations

속한 조직을 id, name, role과 함께 나열합니다.

POST/v1/organizations

{"name": "..."}로 조직을 만들고 사용자를 소유자로 지정합니다. {"id": "org_...", "name": "...", "role": "owner"}와 함께 201을 반환합니다.

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입니다. token, url, email_delivery와 함께 201을 반환합니다.

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 값은 한 번만 반환됩니다. 응답을 닫기 전에 저장하세요.

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와 같은 본문을 반환합니다. 시간당 최대 20회 업로드할 수 있습니다.

DELETE/v1/me/avatar

사진을 제거합니다.

POST/v1/me/password

{"current_password": "...", "new_password": "..."}로 비밀번호를 변경합니다. 새 비밀번호는 12~72바이트입니다. 다른 세션은 로그아웃되고, 요청한 세션은 로그인 상태를 유지합니다. 시간당 최대 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": null}.

GET/v1/organizations/{id}/deployments

등록된 설치본을 나열합니다.

POST/v1/organizations/{id}/deployments

{"name": "..."}로 설치본을 등록하고, Ephemeral이 생성한 머신 ID(또는 직접 보낸 machine_id)와 함께 라이선스 토큰을 한 번만 반환합니다.

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

설치본을 비활성화합니다.

배포 라이선스에서 이 필드와 설치본에서 토큰을 사용하는 방법을 설명합니다.