Authentication API

REST endpoints for registering, logging in, and managing your app's users. All SDK auth endpoints use your project's public API key.

Base URL & auth header

Base URL: https://api.koolbase.com/v1/sdk

All requests require:
  x-api-key: pk_live_your_public_key_here

Endpoints

POST/sdk/auth/registerCreate a new user account

POST/sdk/auth/loginLogin and receive a session token

POST/sdk/auth/logoutInvalidate the current session

GET/sdk/auth/meGet the currently authenticated user

POST/sdk/auth/verify-emailVerify email with a token

POST/sdk/auth/send-verificationSend a verification email

POST/sdk/auth/forgot-passwordRequest a password reset email

POST/sdk/auth/reset-passwordReset password using a token

POST /sdk/auth/register

// Request
{
  "email": "user@example.com",
  "password": "securepassword"
}

// Response 201
{
  "id": "uuid",
  "email": "user@example.com",
  "verified": false,
  "created_at": "2026-01-01T00:00:00Z"
}

POST /sdk/auth/login

// Request
{
  "email": "user@example.com",
  "password": "securepassword"
}

// Response 200
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "verified": true,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

Authenticated endpoints

After login, include the token in the Authorization header for endpoints that require authentication: Authorization: Bearer <token>

GET /sdk/auth/me

// Request headers
Authorization: Bearer <session_token>

// Response 200
{
  "id": "uuid",
  "email": "user@example.com",
  "verified": true,
  "created_at": "2026-01-01T00:00:00Z"
}

POST /sdk/auth/forgot-password

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

// Response 200 (always succeeds — prevents email enumeration)
{ "message": "If that email exists, a reset link has been sent." }

POST /sdk/auth/reset-password

// Request
{
  "token": "reset_token_from_email",
  "password": "newSecurePassword123"
}

// Response 200
{ "message": "Password updated successfully." }

// Error responses
// 400 token_expired  — token is older than 1 hour
// 400 token_invalid  — token not found or already used

Error codes

400invalid_credentialsWrong email or password

400email_not_verifiedUser must verify email before logging in

400token_expiredPassword reset token has expired (1 hour TTL)

400token_invalidToken not found or already used

401unauthorizedMissing or invalid session token

403user_disabledAccount has been disabled by project admin

409email_takenEmail already registered