Skip to content

HTTP Interface

Authara exposes an HTTP interface that is intended for both browser-based authentication flows and programmatic access by applications.

The HTTP surface is divided into two categories:

  • Browser routes – HTML pages and browser authentication flows
  • JSON API – programmatic endpoints used by applications and SDKs

Base Path

Authara is typically mounted under the /auth path behind a reverse proxy or gateway.

Example routing:

/auth/*  → Authara
/*       → Application

This allows Authara to run alongside an existing application without taking over the root domain.

Browser Routes

Browser routes provide the built-in authentication interface used by end users.

Examples include:

/auth/login
/auth/signup
/auth/logout

These endpoints return HTML pages and are intended to be accessed directly by a web browser.

Typical usage pattern:

  1. A user requests a protected page in the application
  2. The application detects the user is not authenticated
  3. The application redirects the user to /auth/login
  4. Authara performs the login flow
  5. The user is redirected back to the application

Browser routes may accept query parameters such as:

/auth/login?return_to=/dashboard

The return_to parameter specifies where the user should be redirected after successful authentication.

For detailed behavior of browser routes, see:

JSON API

Authara also exposes a minimal JSON API for programmatic access.

All API endpoints are available under:

/auth/api/v1

These endpoints are primarily used by:

  • backend applications
  • SDKs
  • browser helper libraries
  • integration services

Examples:

GET  /auth/api/v1/user
POST /auth/api/v1/sessions/refresh

See the API documentation for details:

Authentication

Authenticated API requests rely on session cookies issued by Authara.

The most important cookies include:

  • authara_access – short-lived access token
  • authara_refresh – refresh token
  • authara_csrf – CSRF protection token

For full details, see:

CSRF Protection

State-changing requests require CSRF protection.

Clients must include the CSRF token in the request header:

X-CSRF-Token: <csrf-token>

The token must match the value stored in the authara_csrf cookie.

The token may also be submitted through a hidden form field in HTML forms.

See:

Security Headers

Authara sets security headers on its HTTP responses by default:

  • Content-Security-Policy
  • X-Frame-Options
  • X-Content-Type-Options
  • Referrer-Policy

These headers harden the built-in authentication UI and API responses against common browser-side risks such as clickjacking, MIME sniffing, referrer leakage, and unexpected script or asset loading.

When Google OAuth is enabled, the Content Security Policy allows the Google Identity Services origins required by the login and account-linking UI.

Versioning

The JSON API uses path-based versioning.

Current version:

/auth/api/v1

Future versions may introduce additional endpoints under new paths such as:

/auth/api/v2

Existing versions will remain stable for compatibility.

Summary

Authara's HTTP interface consists of two clearly separated layers:

  • Browser routes for authentication flows
  • JSON API for programmatic access

Applications typically interact with Authara by:

  • redirecting users to browser routes such as /auth/login
  • consuming authenticated session state through cookies
  • optionally calling the JSON API when needed