Authentication

Two credentials, deliberately separate: a session for a person at a browser, a bearer token for a machine. The session mints tokens; the token cannot mint anything.

Magic link

POST /v1/auth/request   { "email": "[email protected]" }   → 202
GET  /v1/auth/verify?token=…                             → 200 + Set-Cookie

The link is single-use and lives 15 minutes.

202 means 'we have your request', not 'we sent an email'

POST /v1/auth/request answers 202 to any well-formed address — whether or not an account exists, whether or not the address is invited, and even if the send itself failed. Anything else would turn sign-in into a way to ask whether a given address is registered here, from anyone, for any address in the world.

A consumed link, an expired one and a forged one also answer identically, byte for byte. A difference between them would say which guess was once real.

Rate limits. Five requests per 15 minutes per address, twenty per 15 minutes per IP. Both answer 429 with Retry-After and the same body — which limit you hit is not part of the answer.

The session cookie

Set-Cookie: plune_session=…; Max-Age=604800; Path=/; HttpOnly; Secure; SameSite=Lax

Seven days, HttpOnly (script cannot read it), Secure, and SameSite=Lax — which is what stops a cross-site POST from carrying it. The value is signed; a cookie with the wrong signature is a 401, not an unknown user.

Note

Seven days is short on purpose. There is no per-session revocation, so the lifetime is the only real control over a stolen session — and signing back in costs one click for anyone who was away a week.

API tokens

POST   /v1/tokens        → 201 { "token": "plune_…" }   ← the only time the value exists
GET    /v1/tokens        → the list, metadata only
DELETE /v1/tokens/{id}   → 204

Only a hash of the token is stored, so the list can never show you the value again and a database leak yields nothing usable. Send it as Authorization: Bearer plune_….

Ninety days. Long enough to survive the thing a token exists for — a pipeline configured once and left alone — and short enough to be distinguishable from forever. The expiry is shown twice: beside the value when you create it, and in the list afterwards. The second one matters more, since “why did my CI stop?” arrives months after anyone thought about the token.

Ten live tokens per account. Expired ones do not occupy a slot. The list says “N of 10”, and past the ceiling the Generate button is disabled with the way out named — revoke one; the API answers 409 with the same explanation. Minting has a three-second cooldown: a second request inside it answers 429 with Retry-After: 3, and the dashboard keeps the button down for those three seconds so you do not see that answer by accident.

Signing out does not revoke tokens

Tokens outlive the session that created them — CI has no session to sign out of. Revoke them explicitly, one at a time or all at once, from Settings → API tokens. Revocation is immediate and cannot be undone; mint a new one.