ReferenceHTTP APIAuth
Email/password login; sets the session cookie
POST
Checks an email and password and starts a browser session: the response sets the __Host-werft_session cookie (HttpOnly, Secure, SameSite=Lax) for 14 days, and the expiry slides forward while the session is used. A user keeps at most 10 live sessions; a new login drops the oldest. This is for the web app; scripts and servers use an API key.
Auth: public; no credential. Idempotency-Key: ignored.
X-Requested-With*"werft-web"Always required: the literal werft-web.
Value in
"werft-web"application/json- body
email*stringMatch
^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Format
emailLength
length <= 254password*stringLength
12 <= lengthSigned in; the response sets the session cookie. scopes are the ones the workspace role holds.
application/json- response
user_id*stringMatch
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format
uuidworkspace_id*stringMatch
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format
uuidrole*stringValue in
"owner""admin""member"scopes*array<>expires_at*stringMatch
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$Format
date-timecurl -X POST 'https://example.com/v1/auth/login' \ -H 'X-Requested-With: werft-web' \ -H 'Content-Type: application/json' \ -d '{ "email": "owner@example.com", "password": "correct horse battery staple"}'Example Response
{ "user_id": "3e7f1a90-5c2d-4b8e-8f61-2a9d0c4b7e35", "workspace_id": "9d2c4e61-8a3b-4f70-b1e5-6c0a7d3f2b98", "role": "owner", "scopes": [ "sessions:read", "sessions:write", "sessions:approve", "sessions:control", "sessions:recover" ], "expires_at": "2026-10-25T09:00:00Z"}