HTTP API reference

Authenticate with Authorization: Bearer <token> on every request. Le token est soit :

• Un access_token JWT Keycloak (browser, dashboard web) — emis par auth[.uat].ilygo.ch/realms/ilygo via OIDC PKCE. TTL 1h, refresh silencieux.
• Une API key icm_xxx (CLI / MCP) — generee depuis le dashboard, longue duree, scopee au user.

Les endpoints retournent 401 si pas de bearer valide, 403 si le compte est desactive. Les donnees sont scopees a l'utilisateur authentifie.

Auth

GET    /auth/me             Returns { user, via: "jwt" | "api_key", roles }
                            JIT provisioning sur premier acces avec JWT
                            inconnu (cree un user par kc_sub).

Le signup, login, logout, reset password, verification email, change password se passent cote Keycloak, pas via cette API. Voir auth[.uat].ilygo.ch/realms/ilygo/protocol/openid-connect/....

API keys

GET    /api-keys
POST   /api-keys            Body: { name, expiresInDays? }
                            Returns the bearer token ONCE in the response.
DELETE /api-keys/:id

Objects (encrypted content envelopes)

PUT    /objects/:hash       Body: application/octet-stream
                            Server verifies sha256(body) === :hash.
GET    /objects/:hash       → application/octet-stream
HEAD   /objects/:hash       Existence check

Wraps (encrypted CEK envelopes)

PUT    /wraps/:hash         Body: 66 bytes (the wrap envelope).
                            The matching object must already exist.
GET    /wraps/:hash
DELETE /wraps/:hash

Refs (CAS-protected pointers)

GET    /refs/:name
PUT    /refs/:name          Body: { hash, expect: string | null }
                            "expect" is the etag CAS — null to create.
                            Also accepts If-Match header.
DELETE /refs/:name          Requires If-Match header.

Commits (parent-link index)

PUT    /commits/:hash       Body: { parent: hash | null }
                            The commit object must already exist.
GET    /commits?from=hash&limit=N
                            Walks the parent chain.
GET    /commits/:hash       Single commit metadata.

Health

GET    /health              Public, no auth.