Authentication

Most API requests authenticate via a Personal Access Token (PAT) in the X-API-Key header. Generate one from the API Keys page in the dashboard — the full key is shown only once.

Header	Required	Description
`X-API-Key`	Yes	Your Personal Access Token
`Authorization`	—	`Bearer <accessToken>` — for JWT-based flows

Base URL

https://api.sieve.godel-labs.ai

Example

curl -sS \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/scans?limit=20'

Exchanging a PAT for a JWT

If your workflow needs a short-lived JWT, exchange your PAT at POST /api/keys/exchange:

curl -sS -X POST \
  -H 'X-API-Key: <YOUR_PAT>' \
  'https://api.sieve.godel-labs.ai/api/keys/exchange'

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "a1b2c3d4-...",
  "expiresIn": 900
}

Then pass the JWT as a Bearer token:

curl -sS \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  'https://api.sieve.godel-labs.ai/api/scans?limit=20'

Auth Endpoints

The following endpoints handle account registration, login, email verification, token lifecycle, and password recovery.

Register

`POST /api/auth/register`

Creates a new user account. An email with a 6-digit verification code is sent to the provided address.

Request Body

{
  "email": "alice@example.com",
  "password": "SecurePass123",
  "firstName": "Alice",
  "lastName": "Smith",
  "cf-turnstile-response": "<TURNSTILE_TOKEN>"
}

Field	Required	Description
`email`	Yes	Valid email address
`password`	Yes	Min 8 chars, must contain uppercase, lowercase, and a digit
`firstName`	No	User's first name
`lastName`	No	User's last name
`cf-turnstile-response`	Conditional	Cloudflare Turnstile token (required when Turnstile is enabled)

Response (201)

{
  "requiresVerification": true,
  "message": "Account created. A verification code has been sent to your email."
}

Log In

`POST /api/auth/login`

Authenticates with email and password. Returns a JWT access token and a refresh token.

Request Body

{
  "email": "alice@example.com",
  "password": "SecurePass123"
}

Response (200)

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "a1b2c3d4-...",
  "user": {
    "id": "usr_123456",
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": "Smith",
    "role": "user"
  }
}

Field	Description
`accessToken`	Short-lived JWT (15 min). Pass as `Authorization: Bearer <token>`.
`refreshToken`	Long-lived token. Exchange at `POST /api/auth/refresh`.

Verify Email

`POST /api/auth/verify-email`

Verifies the account using the 6-digit code sent during registration. Issues tokens on success.

Request Body

{
  "email": "alice@example.com",
  "code": "482913"
}

Response (200)

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "a1b2c3d4-...",
  "user": {
    "id": "usr_123456",
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": "Smith",
    "role": "user"
  }
}

Resend Verification Code

`POST /api/auth/resend-verification`

Sends a new 6-digit verification code to the given email. Rate-limited to once per minute per user.

Request Body

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

Response (200)

{
  "success": true,
  "message": "If an unverified account exists with this email, a new code has been sent."
}

Refresh Access Token

`POST /api/auth/refresh`

Exchanges a valid refresh token for a new access token and a rotated refresh token.

Request Body

{
  "refreshToken": "a1b2c3d4-..."
}

Response (200)

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "e5f6g7h8-..."
}

Log Out

`POST /api/auth/logout`

Revokes the provided refresh token. Requires a valid JWT in the Authorization header.

Request Body

{
  "refreshToken": "a1b2c3d4-..."
}

Response (200)

{
  "success": true,
  "message": "Logged out successfully"
}

Get Current User

`GET /api/auth/me`

Returns the authenticated user's profile, including linked OAuth providers.

Example

curl -sS \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  'https://api.sieve.godel-labs.ai/api/auth/me'

Response (200)

{
  "id": "usr_123456",
  "email": "alice@example.com",
  "emailVerified": true,
  "firstName": "Alice",
  "lastName": "Smith",
  "avatarUrl": null,
  "role": "user",
  "createdAt": "2026-01-10 08:00:00",
  "linkedProviders": ["google"]
}

List Auth Providers

`GET /api/auth/providers`

Returns which authentication methods are currently enabled on the server.

Example

curl -sS 'https://api.sieve.godel-labs.ai/api/auth/providers'

Response (200)

{
  "password": true,
  "google": true,
  "github": false,
  "microsoft": false
}

Forgot Password

`POST /api/auth/forgot-password`

Sends a password reset link to the provided email address (if an account exists). Always returns 200 to prevent email enumeration.

Request Body

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

Response (200)

{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent."
}

Reset Password

`POST /api/auth/reset-password`

Resets the account password using the token from the reset email. All existing sessions are revoked on success.

Request Body

{
  "token": "<RESET_TOKEN>",
  "password": "NewSecurePass456"
}

Field	Required	Description
`token`	Yes	Token from the password reset email link
`password`	Yes	New password (min 8 chars, uppercase, lowercase, digit)

Response (200)

{
  "success": true,
  "message": "Password has been reset successfully. Please login with your new password."
}

Authentication

On this page