Organisations

Sur le service hébergé, les organisations, les membres, les clés API, les crédits et les licences de déploiement se gèrent via l'API d'organisation, à l'adresse https://ephemer.al/v1. Le portail client et le tableau de bord l'utilisent pour vous ; cette page s'adresse aux scripts et aux intégrations.

Authentification

Ces endpoints agissent au nom d'une personne. Connectez-vous avec POST /v1/auth/login et envoyez le token renvoyé comme jeton bearer. Les sessions durent 30 jours ; POST /v1/auth/logout en termine une plus tôt.

Terminal

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

La réponse est {"token": "...", "user": {...}, "organizations": [...]}. Chaque organisation a un id, un name et votre role. Tout ce qui suit, à l'exception du listage et de la création d'organisations et de l'acceptation d'une invitation, exige le rôle de propriétaire ou d'administrateur dans l'organisation indiquée dans le chemin.

Les clés API sont refusées ici

Les clés API d'organisation, y compris les clés admin, ne peuvent pas appeler les endpoints des membres, des clés, de la facturation ou des licences. Une clé divulguée ne peut ainsi ni ajouter de personnes, ni émettre de clés, ni dépenser d'argent. Elles peuvent lire le solde de leur propre organisation.

GET/v1/organizations

Liste les organisations dont vous faites partie, chacune avec id, name et role.

POST/v1/organizations

Crée une organisation à partir de {"name": "..."} et vous en fait propriétaire. Renvoie 201 avec {"id": "org_...", "name": "...", "role": "owner"}.

PATCH/v1/organizations/{id}

Propriétaire ou admin. Renomme l'organisation avec {"name": "..."}. Le nom est rogné et doit compter de 1 à 200 caractères. Renvoie {"id": "org_...", "name": "...", "role": "owner"}. Les membres reçoivent 403.

Membres

GET/v1/organizations/{id}/members

Liste les membres avec id, email, name, role et avatar_url.

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

Retire un membre. Les administrateurs peuvent retirer des membres ; seul le propriétaire peut retirer un administrateur. Le propriétaire ne peut pas être retiré.

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

Propriétaire uniquement. Change le rôle d'un membre avec {"role": "admin"} ou {"role": "member"}.

POST/v1/organizations/{id}/ownership

Propriétaire uniquement. Transfère la propriété à un membre existant avec {"user_id": "..."}. Vous devenez administrateur.

Invitations

POST/v1/organizations/{id}/invitations

Invite quelqu'un avec {"email": "...", "role": "member"}. role vaut admin ou member. Renvoie 201 avec token, url et email_delivery.

email_delivery vaut accepted lorsque le fournisseur d'e-mail a pris le message en charge, ce qui ne garantit pas qu'il soit arrivé dans la boîte de réception. S'il vaut unavailable ou failed, transmettez l'url renvoyée en privé. Les invitations expirent au bout de 7 jours. La personne invitée l'accepte avec POST /v1/invitations/accept et {"token": "..."}, connectée avec l'adresse e-mail invitée.

Clés API

GET/v1/organizations/{id}/keys

Liste les clés avec id, name, role et created_at. Les secrets ne sont jamais listés.

POST/v1/organizations/{id}/keys

Crée une clé à partir de {"name": "...", "role": "member"}. role vaut member ou admin et member par défaut.

201 Created

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

La valeur key n'est renvoyée qu'une seule fois. Conservez-la avant de fermer la réponse.

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

Révoque la clé immédiatement.

Profil

Ces endpoints exigent une session utilisateur connectée ; les clés API sont refusées. Les utilisateurs, ainsi que chaque entrée de membres, portent avatar_url : un chemin tel que /v1/users/usr_…/avatar?v=3f2a…, ou null.

PUT/v1/me/avatar

L'image brute comme corps, avec Content-Type image/png, image/jpeg ou image/webp, 256 Kio au maximum. Renvoie le même corps que GET /v1/auth/me. 20 imports par heure au maximum.

DELETE/v1/me/avatar

Supprime l'image.

POST/v1/me/password

Change votre mot de passe avec {"current_password": "...", "new_password": "..."}. Le nouveau mot de passe fait de 12 à 72 octets. Vos autres sessions sont déconnectées ; celle qui fait la requête reste connectée. 10 tentatives par heure au maximum.

GET/v1/users/{user_id}/avatar

L'image, pour cet utilisateur et les personnes qui partagent une organisation avec lui ; toute autre personne reçoit 404. L'URL change lorsque l'image change : elle peut donc être mise en cache indéfiniment.

Facturation

Dans ces endpoints, les montants Stripe sont en cents et les montants du portefeuille en micros. Voir budgets et facturation.

GET/v1/organizations/{id}/balance

N'importe quel membre, ou une clé API de l'organisation. Renvoie {"balance_micros": ..., "reserved_micros": ..., "available_micros": ...} : crédits détenus, réservés pour des exécutions non réglées, et disponibles pour de nouvelles exécutions. Comparez available_micros au budget d'une exécution avant de la lancer.

GET/v1/organizations/{id}/billing

Renvoie le portefeuille et les paramètres de paiement.

balance_micros, reserved_micros, available_microsinteger

Crédits détenus, réservés pour des exécutions non réglées, et disponibles pour de nouvelles exécutions.

ledgerarray

Les 100 dernières écritures, chacune avec amount_micros, description, created_at et, le cas échéant, run_id, payment_id et topup_id.

purchase_limitsobject

min_amount_cents, max_amount_cents et min_threshold_cents. Validez à partir de ces valeurs plutôt que de coder les limites en dur.

auto_topupobject

enabled, threshold_cents, amount_cents, payment_method_saved et last_topup_status.

payment_methodobject | null

La carte utilisée pour les recharges : brand, last4, exp_month, exp_year et source.

payment_method_syncstring

synced, ou unavailable lorsque Stripe n'a pas pu être joint. Un échec de consultation ne signifie pas qu'il n'y a pas de carte.

stripe_configuredboolean

Indique si les paiements sont disponibles.

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

Lance un achat de crédits avec {"amount_cents": 2500} et renvoie {"url": "..."} pour Stripe Checkout. Ajoutez "save_payment_method": true pour enregistrer la carte en vue des recharges automatiques. Les montants vont de 500 à 1 000 000 cents.

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

Renvoie {"url": "..."} pour le portail client Stripe, où les cartes se gèrent.

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

Active la recharge automatique avec {"enabled": true, "threshold_cents": 1000, "amount_cents": 5000, "consent": true}, ou la désactive avec {"enabled": false}. L'activation exige une carte enregistrée.

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

Historique des paiements, les plus récents d'abord. Accepte limit (de 1 à 100, 25 par défaut) et cursor, et renvoie {"payments": [...], "next_cursor": "..."}. Chaque paiement a amount_cents, refunded_cents, disputed_cents, refund_status, created_at, topup_id et receipt_endpoint.

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

Renvoie {"url": "..."} pour le reçu Stripe, ou 404 si Stripe n'en a pas fourni.

Licences de déploiement

GET/v1/organizations/{id}/license

Le droit d'auto-hébergement de l'organisation, ou {"entitlement": null}.

GET/v1/organizations/{id}/deployments

Liste les installations enregistrées.

POST/v1/organizations/{id}/deployments

Enregistre une installation avec {"name": "..."} et renvoie son jeton de licence une seule fois, avec l'ID de machine généré par Ephemeral (ou le machine_id que vous envoyez).

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

Désactive une installation.

Licences de déploiement décrit ces champs et la façon dont les installations utilisent le jeton.