Auth — /v1/auth

All auth endpoints live at /v1/auth/. None require an Authorization header unless marked requires session.

---

POST /v1/auth/register

Create a new user account and organization.

Request

{
  "org_name": "Acme AI",
  "email": "[email protected]",
  "password": "min-8-chars"
}

Response 201

{
  "user": {
    "user_id": "usr_abc123",
    "email": "[email protected]",
    "email_verified": false,
    "org_id": "org_xyz789"
  }
}

Errors

Status	Error	Reason
400	validation_error	Missing or invalid fields
409	—	Email already registered

A verification email is sent automatically.

---

POST /v1/auth/login

Exchange email + password for a signed JWT (valid 24h). If 2FA is enabled on the account, a challenge token is returned instead of a session token.

Request

{
  "email": "[email protected]",
  "password": "your-password"
}

Response 200 — 2FA disabled

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "user_id": "usr_abc123",
    "email": "[email protected]",
    "email_verified": true,
    "org_id": "org_xyz789"
  }
}

Response 200 — 2FA enabled

{
  "requires_2fa": true,
  "challenge_token": "ch_7f3kx9mq..."
}

When requires_2fa is true, submit the OTP to POST /v1/auth/verify-2fa to receive a session token.

Errors

Status	Reason
400	Validation error
401	Invalid credentials

---

POST /v1/auth/verify-2fa

Exchange a 2FA challenge token + OTP for a session JWT. The challenge token is single-use and burned on first use (correct or incorrect). After 5 incorrect attempts, the challenge is permanently invalidated.

Request

{
  "challenge_token": "ch_7f3kx9mq...",
  "otp": "123456"
}

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "user_id": "usr_abc123",
    "email": "[email protected]",
    "email_verified": true,
    "org_id": "org_xyz789"
  }
}

Errors

Status	Reason
400	Missing or invalid fields
401	Wrong OTP — challenge token is now burned
429	Too many failed attempts

Full 2FA flow

# Step 1: Login
curl -X POST https://api.certivu.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "••••••••" }'
# → { "requires_2fa": true, "challenge_token": "ch_7f3kx9mq..." }

# Step 2: Submit OTP from authenticator app
curl -X POST https://api.certivu.ai/v1/auth/verify-2fa \
  -H "Content-Type: application/json" \
  -d '{ "challenge_token": "ch_7f3kx9mq...", "otp": "123456" }'
# → { "token": "eyJ...", "user": { ... } }

---

POST /v1/auth/logout

Requires session. Blocklists the current JWT so it cannot be reused, even if it has not yet expired. The client should also discard the token locally.

Response 200

{ "success": true }

---

GET /v1/auth/me

Requires session. Returns the current user and their organization.

Response 200

{
  "user": {
    "user_id": "usr_abc123",
    "email": "[email protected]",
    "email_verified": true,
    "org_id": "org_xyz789",
    "created_at": "2026-05-01T12:00:00Z"
  },
  "org": {
    "org_id": "org_xyz789",
    "name": "Acme AI",
    "plan": "starter"
  }
}

---

POST /v1/auth/verify-email

Confirm an email address using the token from the verification email.

Request

{ "token": "<verification-token>" }

Response 200

{ "success": true }

Errors

Status	Reason
400	Token missing or malformed
400	Token expired or already used

---

POST /v1/auth/resend-verification

Re-send the email verification link.

Request

{ "email": "[email protected]" }

Response 200

{ "success": true }

Always returns 200 to prevent email enumeration.

---

POST /v1/auth/forgot-password

Send a password reset link to the given email address.

Request

{ "email": "[email protected]" }

Response 200

{ "success": true }

Always returns 200 even if the email doesn’t exist (prevents enumeration). Reset links expire after 1 hour.

---

POST /v1/auth/reset-password

Set a new password using a valid reset token.

Request

{
  "token": "<reset-token-from-email>",
  "password": "new-password-min-8"
}

Response 200

{ "success": true }

Errors

Status	Reason
400	Validation error
400	Token expired or already used

---

Session JWT format

The JWT payload contains:

{
  "user_id": "usr_abc123",
  "email": "[email protected]",
  "org_id": "org_xyz789",
  "iat": 1748390400,
  "exp": 1748476800
}

Algorithm: HS256. Expiry: 24 hours.

Pass the token as a Bearer header on session-protected endpoints:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The same Authorization: Bearer header also accepts ctv_key_… API keys on all non-auth routes — the backend distinguishes by prefix.