Auth API

Base path: /api/auth

Note

Auth endpoints do not require a bearer token, except where noted.

Endpoints

Method	Path	Auth required	Description
GET	/api/auth/bootstrap	No	Check if setup is needed
POST	/api/auth/register	No (if 0 users)	Create user account
POST	/api/auth/login	No	Username/password login
POST	/api/auth/validate	Yes	Validate token
POST	/api/auth/logout	Yes	End session
POST	/api/auth/keys	Yes (or No if 0 keys)	Create API key
GET	/api/auth/keys	Yes	List API keys
DELETE	/api/auth/keys/{id}	Yes	Revoke API key

---

GET /api/auth/bootstrap

Check whether first-time setup is needed. Used by the UI to redirect to /setup.

curl http://localhost:18781/api/auth/bootstrap

Response:

{ "needs_setup": false }

---

POST /api/auth/register

Create a user account. Only succeeds if no users exist yet.

curl -X POST http://localhost:18781/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "mypassword123"}'

Field	Type	Required	Description
username	string	Yes	Minimum 3 characters
password	string	Yes	Minimum 8 characters

Response: 201 Created

{
  "user_id": "usr_abc123",
  "username": "alice",
  "token": "sess_abc123...",
  "token_type": "session",
  "message": "Account created successfully"
}

---

POST /api/auth/login

Authenticate with username and password. Returns a session token.

curl -X POST http://localhost:18781/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "mypassword123"}'

Response: 200 OK

{
  "token": "sess_abc123...",
  "token_type": "session",
  "expires_in": 86400,
  "user": { "id": "usr_xyz", "username": "alice" }
}

---

POST /api/auth/validate

Validate a token (session or API key). Requires auth.

curl -X POST http://localhost:18781/api/auth/validate \
  -H "Authorization: Bearer snip_your_key"

Response: 200 OK

{ "valid": true, "token_type": "api_key" }

---

POST /api/auth/logout

End the current session. Requires auth.

curl -X POST http://localhost:18781/api/auth/logout \
  -H "Authorization: Bearer sess_abc123"

Response: 200 OK

{ "success": true }

---

POST /api/auth/keys

Create a new API key. Requires auth (or no auth if zero keys exist).

curl -X POST http://localhost:18781/api/auth/keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI automation"}'

Field	Type	Required	Description
name	string	Yes	Human-readable label

Response: 200 OK

{
  "id": "key_abc123",
  "name": "CI automation",
  "key": "snip_abc123...",
  "created_at": "2026-03-01T09:00:00Z"
}

Caution

The key is shown only once. Store it securely — it cannot be retrieved again.

---

GET /api/auth/keys

List all API keys. Requires auth.

curl http://localhost:18781/api/auth/keys \
  -H "Authorization: Bearer $API_KEY"

Response: 200 OK

{
  "keys": [
    { "id": "key_abc123", "name": "CI automation", "created_at": "...", "last_used": "..." }
  ]
}

---

DELETE /api/auth/keys/:id

Revoke an API key permanently. Requires auth.

curl -X DELETE http://localhost:18781/api/auth/keys/key_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response: 204 No Content