Skip to content
Korta

Authentication

Getting credentials

Section titled “Getting credentials”

JWT (Bearer)

Section titled “JWT (Bearer)”
  1. Register a user: POST /auth/register
  2. Verify email: GET /auth/verify/:token (idempotent)
  3. Login: POST /auth/login
  4. Use returned accessToken as Bearer token.

Registration behavior:

  • New email: 201 with verification-required message.
  • Existing unverified email: 200 and verification email is resent.
  • Existing verified email: 409 conflict.

Verify behavior:

  • First valid token use: 200 -> Email verified successfully.
  • Repeated valid token use: 200 -> Email already verified. You can sign in.
  • Invalid/expired token: 404.

API Key

Section titled “API Key”
  1. Authenticate with JWT.
  2. Create/regenerate key: POST /auth/api-key/regenerate
  3. Use returned key in X-API-Key.

Behavior details:

  • X-API-Key is accepted on authMiddleware routes (for example: POST /urls, GET /urls/my-links, PATCH/DELETE /urls/:shortId, GET /auth/me, POST /auth/change-password, DELETE /auth/account).
  • GET /auth/api-key and POST /auth/api-key/regenerate are Bearer-only; X-API-Key returns 401 (Bearer token required).
  • POST /urls/public uses optional auth: invalid X-API-Key does not block anonymous creation.

Using tokens

Section titled “Using tokens”
Authorization: Bearer <token>

For API key auth:

X-API-Key: <api_key>

Token lifecycle

Section titled “Token lifecycle”
  • Issue: on successful POST /auth/login (or OAuth callback flow).
  • Expiration: JWT expires in 1 hour.
  • Rotation: obtain a new JWT by logging in again.
  • Revocation: no token blacklist currently; JWT invalidates on expiry. API keys can be rotated via POST /auth/api-key/regenerate (old key becomes unusable).

Error cases

Section titled “Error cases”

401 Unauthorized

Section titled “401 Unauthorized”
  • Missing/invalid/expired JWT.
  • Invalid API key.
  • User not verified.

403 Forbidden

Section titled “403 Forbidden”
  • Authenticated user lacks ownership/permission for target resource.

409 Conflict

Section titled “409 Conflict”
  • Registration with already used verified email.

503 Service Unavailable

Section titled “503 Service Unavailable”
  • Verification email provider is temporarily unavailable during registration.
  • Registration is rolled back (no partial account is kept).

Password recovery

Section titled “Password recovery”
  • POST /auth/forgot-password: always returns generic 200 message.
  • POST /auth/reset-password: returns 200 on success, 400 for invalid/expired token or invalid body.
  • Successful reset also sets isVerified = true and invalidates the reset token (one-time use).