BattleScript
Home › Documentation › API Reference › Authentication API

Authentication API

Overview

Authentication on BattleScript is handled entirely by NextAuth through the catch-all route mounted at /api/auth/[...nextauth]. There are no custom register, login, or logout endpoints, and the platform does not use bearer tokens or JWTs stored in localStorage.

Instead, a successful sign-in establishes an HTTP-only session cookie in the browser. Subsequent requests to the other BattleScript API endpoints are authenticated automatically because the browser sends that cookie with each same-origin request — you do not attach an Authorization header yourself.

Authentication Note

Because authentication relies on the session cookie, calls to protected endpoints (such as POST /api/scripts or GET /api/user/profile) only succeed when made from the browser within an active session. Always include credentials on cross-contextfetch calls (for example credentials: 'include') so the cookie is sent. Requests without a valid session receive a 401 Unauthorizedresponse.

NextAuth Endpoints

The [...nextauth] route handles both GET and POST requests and exposes the standard set of NextAuth sub-routes. You rarely call these directly — the NextAuth client helpers (signIn(), signOut()) drive them for you — but they are documented here for completeness.

GET

/api/auth/session

Description: Returns the current session for the signed-in user, or an empty object when signed out. Authentication is read from the session cookie.

Response (signed in):

{
  "user": {
    "name": "string",
    "email": "string",
    "image": "string"
  },
  "expires": "string"  // ISO 8601 timestamp
}

Response (signed out):

{}

Example:

// Read the current session (cookie sent automatically)
fetch('/api/auth/session', {
  credentials: 'include'
})
.then(response => response.json())
.then(session => {
  if (session.user) {
    console.log('Signed in as', session.user.name);
  } else {
    console.log('Not signed in');
  }
})
.catch(error => console.error('Error:', error));
GET

/api/auth/providers

Description: Lists the authentication providers configured for the platform. Used by the NextAuth client to render the available sign-in options.

GET

/api/auth/csrf

Description: Returns the CSRF token that NextAuth requires for sign-in and sign-out POST requests.

POST

/api/auth/signin

Description: Initiates a sign-in for the requested provider. A GET request renders the built-in sign-in page; a POST (with a CSRF token) begins the provider flow. On success a session cookie is set. Prefer the client helper signIn() over calling this directly.

POST

/api/auth/signout

Description: Ends the current session and clears the session cookie. Requires the CSRF token. Prefer the client helper signOut() over calling this directly.

GETPOST

/api/auth/callback/{provider}

Description: The OAuth callback endpoint that each provider redirects back to after authentication. Handled internally by NextAuth to complete the flow and establish the session.

Authentication Flow

The typical authentication flow for the BattleScript platform is as follows:

  1. The client triggers a sign-in via the NextAuth signIn() helper (which uses /api/auth/signin and the provider callback).
  2. On success, NextAuth sets an HTTP-only session cookie in the browser.
  3. The browser automatically sends that cookie with every same-origin request, so protected API endpoints recognise the signed-in user.
  4. The client can read the current session at any time via GET /api/auth/session.
  5. To sign out, the client calls the signOut() helper (which uses /api/auth/signout), clearing the session cookie.

Related Topics