Authentication Endpoints

Technical Debt Radar uses JWT-based authentication. Access tokens expire after 15 minutes. Refresh tokens expire after 7 days.

All tokens are returned as accessToken and refreshToken in login/signup responses. Include the access token in subsequent requests:

Authorization: Bearer <accessToken>

---

POST /auth/signup

Create a new account with email and password.

Rate limit: 3 requests per minute

Request

curl -X POST https://api.radar.dev/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "SecureP@ss123",
    "name": "Jane Developer"
  }'

const response = await fetch("https://api.radar.dev/v1/auth/signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "dev@example.com",
    password: "SecureP@ss123",
    name: "Jane Developer",
  }),
});
const data = await response.json();

Request Body

Field	Type	Required	Description
email	string	Yes	Valid email address
password	string	Yes	Minimum 8 characters, must include uppercase, lowercase, and number
name	string	Yes	Display name

Response 201 Created

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
  "user": {
    "id": "usr_a1b2c3d4e5",
    "email": "dev@example.com",
    "name": "Jane Developer",
    "createdAt": "2026-03-18T10:30:00.000Z"
  }
}

Errors

Status	Description
400	Validation error (weak password, invalid email)
409	Email already registered
429	Rate limit exceeded

---

POST /auth/login

Sign in with email and password.

Rate limit: 5 requests per minute

Request

curl -X POST https://api.radar.dev/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "SecureP@ss123"
  }'

const response = await fetch("https://api.radar.dev/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "dev@example.com",
    password: "SecureP@ss123",
  }),
});
const { accessToken, refreshToken } = await response.json();

Request Body

Field	Type	Required	Description
email	string	Yes	Registered email address
password	string	Yes	Account password

Response 200 OK

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
  "user": {
    "id": "usr_a1b2c3d4e5",
    "email": "dev@example.com",
    "name": "Jane Developer",
    "createdAt": "2026-03-18T10:30:00.000Z"
  }
}

Errors

Status	Description
401	Invalid email or password
429	Rate limit exceeded (5 attempts/min)

---

POST /auth/refresh

Exchange a valid refresh token for a new access token and refresh token pair. Use this when the access token expires (15-minute TTL).

Request

curl -X POST https://api.radar.dev/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "dGhpcyBpcyBhIHJlZnJl..."
  }'

const response = await fetch("https://api.radar.dev/v1/auth/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ refreshToken: storedRefreshToken }),
});
const { accessToken, refreshToken } = await response.json();

Request Body

Field	Type	Required	Description
refreshToken	string	Yes	Previously issued refresh token

Response 200 OK

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "bmV3IHJlZnJlc2ggdG9r..."
}

Errors

Status	Description
401	Refresh token is invalid, expired, or revoked

---

POST /auth/logout

Invalidate the current access token. Requires authentication.

Request

curl -X POST https://api.radar.dev/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

await fetch("https://api.radar.dev/v1/auth/logout", {
  method: "POST",
  headers: { Authorization: `Bearer ${accessToken}` },
});

Response 200 OK

{
  "success": true
}

---

POST /auth/forgot-password

Request a password reset email. Always returns success to prevent email enumeration.

Rate limit: 3 requests per minute

Request

curl -X POST https://api.radar.dev/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com"
  }'

await fetch("https://api.radar.dev/v1/auth/forgot-password", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "dev@example.com" }),
});

Response 200 OK

{
  "message": "If the email exists, a reset link has been sent"
}

---

POST /auth/reset-password

Set a new password using the token from the reset email.

Request

curl -X POST https://api.radar.dev/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "rst_abc123def456...",
    "newPassword": "NewSecureP@ss456"
  }'

await fetch("https://api.radar.dev/v1/auth/reset-password", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    token: "rst_abc123def456...",
    newPassword: "NewSecureP@ss456",
  }),
});

Request Body

Field	Type	Required	Description
token	string	Yes	Reset token from email link
newPassword	string	Yes	New password (same requirements as signup)

Response 200 OK

{
  "message": "Password reset successfully"
}

Errors

Status	Description
400	Token expired or invalid, or password does not meet requirements

---

GET /auth/github

Initiates the GitHub OAuth flow. Redirects the user to GitHub's authorization page.

Request

# Browser redirect — not a typical API call
# Navigate to this URL to start the OAuth flow
https://api.radar.dev/v1/auth/github

Behavior

1. Redirects to https://github.com/login/oauth/authorize with the configured client ID and scopes.
2. After user authorizes, GitHub redirects to /auth/github/callback.

---

GET /auth/github/callback

GitHub OAuth callback. Handles the authorization code exchange and creates or links the user account.

Behavior

1. Exchanges the OAuth code for a GitHub access token.
2. Fetches the GitHub user profile.
3. Creates a new account or links to an existing account (matched by email).
4. Redirects to the frontend with tokens:

https://app.radar.dev/auth/callback?token=<accessToken>&refresh=<refreshToken>

---

GET /auth/google

Initiates the Google OAuth flow. Redirects the user to Google's authorization page.

Request

# Browser redirect — not a typical API call
https://api.radar.dev/v1/auth/google

---

GET /auth/google/callback

Google OAuth callback. Same flow as GitHub callback but using Google profile data.

Behavior

1. Exchanges the OAuth code for a Google access token.
2. Fetches the Google user profile.
3. Creates or links user account by email.
4. Redirects to frontend with tokens.

---

GET /auth/me

Returns the profile of the currently authenticated user.

Request

curl https://api.radar.dev/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

const response = await fetch("https://api.radar.dev/v1/auth/me", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const user = await response.json();

Response 200 OK

{
  "id": "usr_a1b2c3d4e5",
  "email": "dev@example.com",
  "name": "Jane Developer",
  "avatarUrl": "https://avatars.githubusercontent.com/u/12345",
  "provider": "github",
  "createdAt": "2026-03-18T10:30:00.000Z",
  "updatedAt": "2026-03-18T10:30:00.000Z"
}

Errors

Status	Description
401	Missing or invalid access token

---

Token Lifecycle

Signup / Login / OAuth
       │
       ▼
  accessToken (15 min) + refreshToken (7 days)
       │
       │  accessToken expires
       ▼
  POST /auth/refresh
       │
       ▼
  New accessToken + refreshToken
       │
       │  refreshToken expires (7 days)
       ▼
  User must log in again

Store refresh tokens securely (HTTP-only cookie or encrypted storage). Never expose them in URLs or client-side JavaScript.