Authentication

Cognova uses BetterAuth for authentication. All auth endpoints are handled by a catch-all route at /api/auth/* that proxies to BetterAuth's built-in handlers.

Sessions are cookie-based and last 7 days. The session age is refreshed every 24 hours on active use.

Endpoints

BetterAuth exposes a standard set of endpoints. The most commonly used ones are documented below.

Sign Up

POST /api/auth/sign-up/email

Create a new user account with email and password.

Authentication: Not required

Request Body:

Response: 200 OK

{
  "user": {
    "id": "abc-123",
    "name": "Tony",
    "email": "tony@example.com"
  },
  "session": {
    "id": "sess-456",
    "userId": "abc-123",
    "expiresAt": "2025-01-14T00:00:00.000Z"
  }
}

Sign In

POST /api/auth/sign-in/email

Authenticate with email and password. Sets a session cookie on success.

Authentication: Not required

Request Body:

Response: 200 OK

{
  "user": {
    "id": "abc-123",
    "name": "Tony",
    "email": "tony@example.com"
  },
  "session": {
    "id": "sess-789",
    "userId": "abc-123",
    "expiresAt": "2025-01-14T00:00:00.000Z"
  }
}

Sign Out

POST /api/auth/sign-out

End the current session and clear the session cookie.

Authentication: Required

Request Body: None

Response: 200 OK

{
  "success": true
}

Get Session

GET /api/auth/get-session

Return the current user and session information. Useful for checking if a session is still valid.

Authentication: Required

Response: 200 OK

{
  "user": {
    "id": "abc-123",
    "name": "Tony",
    "email": "tony@example.com"
  },
  "session": {
    "id": "sess-789",
    "userId": "abc-123",
    "expiresAt": "2025-01-14T00:00:00.000Z"
  }
}

Returns null if no valid session exists.

API Token Authentication

For non-browser clients (CLI tools, cron scripts), set the COGNOVA_API_TOKEN environment variable and pass it in the request header:

curl -H "X-API-Token: your-token-here" \
  https://your-instance.com/api/tasks

Token authentication maps to the first user in the database. It bypasses cookie-based session validation but provides the same access level.

Session Configuration