Authentication Endpoints

REST API endpoints automatically created by Nuxt Aegis.

Overview

Nuxt Aegis automatically creates authentication endpoints for OAuth flows, token management, and user information.

Authentication Endpoints

GET `/auth/{provider}`

Dual-purpose endpoint that handles both OAuth initiation and callback.

Initial Login (no code parameter):

http

GET /auth/google HTTP/1.1
Host: example.com

Redirects user to OAuth provider's authorization page.

OAuth Callback (with code parameter):

http

GET /auth/google?code=oauth_authorization_code HTTP/1.1
Host: example.com

Exchanges OAuth CODE for tokens, generates authorization CODE, and redirects to /auth/callback?code=....

Query Parameters:

Parameter	Type	Description
`code`	`string`	OAuth authorization CODE from provider
`state`	`string`	CSRF protection state parameter
`error`	`string`	Error code from OAuth provider
`error_description`	`string`	Human-readable error description

Example:

typescript

// Redirect user to login
await navigateTo('/auth/google')

// Or use composable
const { login } = useAuth()
await login('google')

GET `/auth/callback`

Client-side callback page that exchanges authorization CODE for JWT token.

Query Parameters:

Parameter	Type	Required	Description
`code`	`string`	✅	Authorization CODE from server

Example URL:

https://example.com/auth/callback?code=abc123xyz456

This page automatically:

Extracts CODE from URL
Calls /auth/token to exchange CODE for JWT
Stores JWT token
Redirects to configured success URL

Automatic Handling

This endpoint is handled automatically by the module. You don't need to implement it manually.

POST `/auth/token`

Exchange authorization CODE for JWT access token.

Request Body:

json

{
  "code": "abc123xyz456"
}

Response:

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

Error Response:

json

{
  "statusCode": 401,
  "message": "Invalid or expired authorization code"
}

Example:

typescript

const { token } = await $fetch('/auth/token', {
  method: 'POST',
  body: {
    code: 'abc123xyz456'
  }
})

Security Features:

Single-use CODE enforcement (deleted after exchange)
60-second CODE expiration
Cryptographically secure CODE validation

POST `/auth/refresh`

Obtain a new access token using the refresh token cookie.

Request:

http

POST /auth/refresh HTTP/1.1
Host: example.com
Cookie: nuxt-aegis-refresh=refresh_token_value

Response:

json

{
  "success": true,
  "message": "Token refreshed successfully",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Response:

json

{
  "statusCode": 401,
  "message": "Invalid or expired session"
}

Status	Meaning	Refresh cookie
`401`	Missing, unknown, expired, or revoked refresh token	Cleared
`403`	Refresh prohibited, including an impersonated session	Retained
`5xx`	Configuration, storage, token generation, or other unexpected failure	Not cleared

Invalid-session responses use Invalid or expired session; unexpected failures use Token refresh failed without internal details. Expected missing-session requests are not logged as application errors. A 403 alone does not invalidate the original session.

Example:

typescript

const { accessToken } = await $fetch('/auth/refresh', {
  method: 'POST'
  // Refresh token cookie sent automatically
})

// Or use composable
const { refresh } = useAuth()
await refresh()

How it works:

Refresh token sent automatically via HttpOnly cookie
Server validates token from persistent storage
Server retrieves stored user object
Server generates new access token with custom claims
Server optionally rotates refresh token
Server returns new access token

POST `/auth/logout`

End user session and revoke refresh token.

Request:

http

POST /auth/logout HTTP/1.1
Host: example.com
Cookie: nuxt-aegis-refresh=refresh_token_value

Response:

json

{
  "success": true
}

Example:

typescript

await $fetch('/auth/logout', {
  method: 'POST'
})

// Or use composable
const { logout } = useAuth()
await logout()

What happens:

Server retrieves refresh token from cookie
Server deletes refresh token from storage
Server deletes refresh token cookie
User is logged out

GET `/api/user/me`

Get current user information from JWT token.

Request:

http

GET /api/user/me HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response:

json

{
  "sub": "google:123456789",
  "name": "John Doe",
  "email": "john@example.com",
  "picture": "https://example.com/avatar.jpg",
  "provider": "google",
  "role": "admin",
  "iat": 1700000000,
  "exp": 1700003600
}

Error Response:

json

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Example:

typescript

// Client-side with useAuth
const { user } = useAuth()
console.log(user.value)

// Server-side API call
const user = await $fetch('/api/user/me', {
  headers: {
    Authorization: `Bearer ${accessToken}`
  }
})

Provider-Specific Endpoints

Each configured provider gets its own dual-purpose endpoint.

Google

GET /auth/google          # Initiate OAuth
GET /auth/google?code=... # OAuth callback

Auth0

GET /auth/auth0          # Initiate OAuth
GET /auth/auth0?code=... # OAuth callback

GitHub

GET /auth/github          # Initiate OAuth
GET /auth/github?code=... # OAuth callback

Mock Provider

GET /auth/mock          # Initiate mock OAuth
GET /auth/mock?code=... # Mock OAuth callback

Mock Provider Endpoints

The mock provider creates additional endpoints for development/testing:

GET `/mock/authorize`

Mock OAuth authorization endpoint (internal).

POST `/mock/token`

Mock OAuth token endpoint (internal).

GET `/mock/userinfo`

Mock OAuth userinfo endpoint (internal).

Error Handling

All endpoints return standard HTTP error codes:

Status Code	Description
`200`	Success
`400`	Bad Request (missing parameters)
`401`	Unauthorized (invalid/expired token)
`403`	Forbidden (insufficient permissions)
`500`	Internal Server Error
`503`	Service Unavailable

For /auth/refresh, only 401 confirms an invalid session and clears its cookie. Network failures and 5xx do not establish that the session is invalid; 403 rejects the operation, not necessarily the session. See client failure handling.

Error Response Format:

json

{
  "statusCode": 401,
  "message": "Invalid or expired token",
  "error": "Unauthorized"
}

Client Usage

Composable Methods

Recommended approach using useAuth():

typescript

const { login, logout, refresh } = useAuth()

// Login
await login('google')

// Logout
await logout()

// Refresh token
await refresh()

Direct API Calls

Using $fetch for custom flows:

typescript

// Login redirect
await navigateTo('/auth/google')

// Token exchange
const { token } = await $fetch('/auth/token', {
  method: 'POST',
  body: { code: authCode }
})

// Refresh
const { accessToken } = await $fetch('/auth/refresh', {
  method: 'POST'
})

// Logout
await $fetch('/auth/logout', {
  method: 'POST'
})

// Get user
const user = await $fetch('/api/user/me', {
  headers: {
    Authorization: `Bearer ${accessToken}`
  }
})

Server-Side Usage

Protect API endpoints using server utilities:

typescript

// server/routes/api/profile.get.ts
export default defineEventHandler(async (event) => {
  // Require authentication
  const user = await requireAuth(event)
  
  return {
    profile: user
  }
})

Authentication Endpoints ​

Overview ​