Skip to content

api-reference-README.md

Latest commit

 

History

History
129 lines (89 loc) · 2.06 KB

api-reference-README.md

File metadata and controls

129 lines (89 loc) · 2.06 KB

Auth API

Base URL: https://api.lockbox.dev/v1

All requests need Authorization: Bearer <token> header except login/register.

POST /auth/register

curl -X POST https://api.lockbox.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secretpass123"}'

Body

Field Type Notes
email string required
password string min 8 chars
name string optional

Response 201

{
  "id": "usr_x7ka92m",
  "email": "user@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

Errors

  • 400 invalid_email - bad format
  • 400 weak_password - too short or common
  • 409 email_exists - already registered

POST /auth/login

curl -X POST https://api.lockbox.dev/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secretpass123"}'

Response 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 86400,
  "user": {
    "id": "usr_x7ka92m",
    "email": "user@example.com"
  }
}

Token valid for 24h. Pass "remember": true in body for 7 days.

Errors

  • 401 invalid_credentials
  • 403 account_locked - too many attempts, wait 15min

POST /auth/logout

Invalidates token. Returns 204 (no body).

POST /auth/forgot-password

{"email": "user@example.com"}

Always returns 200 even if email doesn't exist (prevents enumeration).

POST /auth/reset-password

{
  "token": "rst_abc123...",
  "password": "newpassword123"
}

Token from email, valid 1 hour.

Rate limits

Endpoint Limit
/auth/login 5/15min
/auth/register 3/hour
everything else 100/min

When limited you get 429 with retry_after in seconds.

Error format

{
  "error": "error_code",
  "message": "Human readable message"
}

Changelog

  • 1.2 (Jan 2024) - added remember option to login
  • 1.1 (Dec 2023) - rate limiting
  • 1.0 (Nov 2023) - initial