Organizaciones

En el servicio alojado, las organizaciones, los miembros, las claves de API, los créditos y las licencias de despliegue se gestionan a través de la API de organizaciones en https://ephemer.al/v1. El portal de clientes y el panel la usan por ti; esta página es para scripts e integraciones.

Autenticación

Estos endpoints actúan en nombre de una persona. Inicia sesión con POST /v1/auth/login y envía el token devuelto como token bearer. Las sesiones duran 30 días; POST /v1/auth/logout termina una antes de tiempo.

Terminal

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

La respuesta es {"token": "...", "user": {...}, "organizations": [...]}. Cada organización tiene id, name y tu role. Todo lo que sigue, salvo listar y crear organizaciones y aceptar una invitación, requiere el rol de propietario o administrador en la organización indicada en la ruta.

Aquí se rechazan las claves de API

Las claves de API de la organización, incluidas las de administrador, no pueden llamar a los endpoints de miembros, claves, facturación o licencias. Así, una clave filtrada no puede añadir personas, emitir claves ni gastar dinero. Sí pueden leer el saldo de su propia organización.

GET/v1/organizations

Lista las organizaciones a las que perteneces, cada una con id, name y role.

POST/v1/organizations

Crea una organización a partir de {"name": "..."} y te convierte en su propietario. Devuelve 201 con {"id": "org_...", "name": "...", "role": "owner"}.

PATCH/v1/organizations/{id}

Propietario o administrador. Cambia el nombre de la organización con {"name": "..."}. El nombre se recorta y debe tener de 1 a 200 caracteres. Devuelve {"id": "org_...", "name": "...", "role": "owner"}. Los miembros reciben 403.

Miembros

GET/v1/organizations/{id}/members

Lista los miembros con id, email, name, role y avatar_url.

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

Elimina a un miembro. Los administradores pueden eliminar miembros; solo el propietario puede eliminar a un administrador. No se puede eliminar al propietario.

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

Solo propietario. Cambia el rol de un miembro con {"role": "admin"} o {"role": "member"}.

POST/v1/organizations/{id}/ownership

Solo propietario. Transfiere la propiedad a un miembro existente con {"user_id": "..."}. Tú pasas a ser administrador.

Invitaciones

POST/v1/organizations/{id}/invitations

Invita a alguien con {"email": "...", "role": "member"}. role es admin o member. Devuelve 201 con token, url y email_delivery.

email_delivery es accepted cuando el proveedor de correo aceptó el mensaje, lo que no garantiza que haya llegado a la bandeja de entrada. Si es unavailable o failed, comparte en privado la url devuelta. Las invitaciones caducan a los 7 días. La persona invitada la acepta con POST /v1/invitations/accept y {"token": "..."}, con la sesión iniciada con la dirección de correo invitada.

Claves de API

GET/v1/organizations/{id}/keys

Lista las claves con id, name, role y created_at. Los secretos nunca se listan.

POST/v1/organizations/{id}/keys

Crea una clave a partir de {"name": "...", "role": "member"}. role es member o admin y por defecto es member.

201 Created

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

El valor de key se devuelve una sola vez. Guárdalo antes de cerrar la respuesta.

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

Revoca la clave de inmediato.

Perfil

Estos requieren una sesión de usuario iniciada; las claves de API se rechazan. Los usuarios, y cada entrada de miembros, incluyen avatar_url: una ruta como /v1/users/usr_…/avatar?v=3f2a…, o null.

PUT/v1/me/avatar

La imagen sin procesar como cuerpo, con Content-Type image/png, image/jpeg o image/webp, de hasta 256 KiB. Devuelve el mismo cuerpo que GET /v1/auth/me. Como máximo 20 subidas por hora.

DELETE/v1/me/avatar

Elimina la imagen.

POST/v1/me/password

Cambia tu contraseña con {"current_password": "...", "new_password": "..."}. La contraseña nueva tiene de 12 a 72 bytes. Se cierran tus otras sesiones; la que hace la solicitud permanece abierta. Como máximo 10 intentos por hora.

GET/v1/users/{user_id}/avatar

La imagen, para ese usuario y las personas que comparten una organización con él; cualquier otra persona recibe 404. La URL cambia cuando cambia la imagen, así que se puede guardar en caché de forma indefinida.

Facturación

El dinero en estos endpoints usa centavos para los importes de Stripe y micros para los importes del monedero. Consulta presupuestos y facturación.

GET/v1/organizations/{id}/balance

Cualquier miembro, o una clave de API de la organización. Devuelve {"balance_micros": ..., "reserved_micros": ..., "available_micros": ...}: créditos disponibles en total, reservados para ejecuciones sin liquidar y disponibles para nuevas ejecuciones. Comprueba available_micros frente al presupuesto de una ejecución antes de iniciarla.

GET/v1/organizations/{id}/billing

Devuelve el monedero y los ajustes de pago.

balance_micros, reserved_micros, available_microsinteger

Créditos disponibles en total, reservados para ejecuciones sin liquidar y disponibles para nuevas ejecuciones.

ledgerarray

Las últimas 100 entradas, cada una con amount_micros, description, created_at y, cuando corresponden, run_id, payment_id y topup_id.

purchase_limitsobject

min_amount_cents, max_amount_cents y min_threshold_cents. Valida con estos valores en lugar de fijar los límites en el código.

auto_topupobject

enabled, threshold_cents, amount_cents, payment_method_saved y last_topup_status.

payment_methodobject | null

La tarjeta que se usa para las recargas: brand, last4, exp_month, exp_year y source.

payment_method_syncstring

synced, o unavailable cuando no se pudo contactar con Stripe. Que la consulta falle no significa que no haya tarjeta.

stripe_configuredboolean

Si los pagos están disponibles.

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

Inicia una compra de créditos con {"amount_cents": 2500} y devuelve {"url": "..."} para Stripe Checkout. Añade "save_payment_method": true para guardar la tarjeta para recargas automáticas. Los importes van de 500 a 1000000 centavos.

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

Devuelve {"url": "..."} del portal de clientes de Stripe, donde se gestionan las tarjetas.

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

Activa la recarga automática con {"enabled": true, "threshold_cents": 1000, "amount_cents": 5000, "consent": true}, o la desactiva con {"enabled": false}. Activarla requiere una tarjeta guardada.

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

Historial de pagos, del más reciente al más antiguo. Acepta limit (de 1 a 100, por defecto 25) y cursor, y devuelve {"payments": [...], "next_cursor": "..."}. Cada pago tiene amount_cents, refunded_cents, disputed_cents, refund_status, created_at, topup_id y receipt_endpoint.

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

Devuelve {"url": "..."} del recibo de Stripe, o 404 si Stripe no ha proporcionado ninguno.

Licencias de despliegue

GET/v1/organizations/{id}/license

El derecho de autoalojamiento de la organización, o {"entitlement": null}.

GET/v1/organizations/{id}/deployments

Lista las instalaciones registradas.

POST/v1/organizations/{id}/deployments

Registra una instalación con {"name": "..."} y devuelve su token de licencia una sola vez, con el ID de máquina que generó Ephemeral (o el machine_id que envíes).

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

Desactiva una instalación.

Licencias de despliegue describe estos campos y cómo usan el token las instalaciones.