API Overview

Learn about the AuthCore API architecture, authentication, and conventions.

Base URL

https://your-domain.com/api

All API endpoints are prefixed with /api. Replace your-domain.com with your actual domain.

Authentication

Browser clients authenticate with the authcore.session-token cookie issued by NextAuth. Server-to-server integrations can forward a short-lived Bearer token that your backend issues and validates.

💡 Tip: Endpoints using the authRoute middleware apply rate limiting and audit logging automatically, so you do not need to bolt on additional guards for public auth flows.

HTTP Methods

GET - Retrieve Data

Fetch resources without side effects

POST - Create Resources

Create new resources

PUT/PATCH - Update Resources

Modify existing resources

DELETE - Remove Resources

Delete resources permanently

Response Format

All responses are in JSON format with appropriate HTTP status codes:

200 OK - Request succeeded

201 Created - Resource created successfully

400 Bad Request - Invalid request data

401 Unauthorized - Missing or invalid authentication

403 Forbidden - Insufficient permissions

404 Not Found - Resource doesn't exist

500 Server Error - Internal server error

Error Handling

Errors follow a consistent structure:

Rate Limiting

Built-in middleware provides sensible defaults:

authRoute (registration, login, magic link): 5 requests per 15 minutes per IP

publicRoute (policy + other read-only endpoints): 20 requests per minute per IP

protected/admin routes: Unlimited, but governed by NextAuth session timeouts.