Authenticate API requests

Overview

Use @antelopejs/interface-auth to sign tokens and inject verified payloads into API handlers. Your application still owns credential checks, payload validation, and permission rules: a valid signature alone does not grant access to a resource.

This interface depends on the Interface API package, which provides the decorator infrastructure for parameter injection.

Core concepts

The authentication system is built around three main layers:

• Token handling - Sign and verify authentication tokens using SignRaw, ValidateRaw, and SignServerResponse.
• Authentication decorators - The @Authentication decorator and CreateAuthDecorator function inject verified user data into handler parameters.
• Customizable pipeline - Configure custom sources, verifiers, and validators to adapt the authentication flow.

Installation

pnpm add @antelopejs/interface-auth

Protect an endpoint

Start with a running AntelopeJS API module and an authentication provider bound to this interface. Installing the package does not configure signing keys or attach a token implementation.

This controller requires a verified token for GET /account. It returns no claims, so you can first check that your provider and transport work before adding payload validation.

import { Controller, Get } from "@antelopejs/interface-api";
import { Authentication } from "@antelopejs/interface-auth";

@Authentication()
class AccountController extends Controller("/account") {
  @Get("")
  status() {
    return { authenticated: true };
  }
}

Send an issued token in x-antelopejs-auth to receive { "authenticated": true }. A missing or invalid token must fail verification before the handler runs. This checks authentication only, not permission to read another user's account.

1. Issue a token after checking credentials. Use token handling to choose SignRaw or SignServerResponse and set an expiry.
2. Choose one transport. The default source reads a raw token from x-antelopejs-auth, then tries ANTELOPEJS_AUTH only when the header is absent. For Authorization: Bearer, use the custom source example.
3. Require authentication. Add a parameter, property, or class decorator to the controller.
4. Enforce your policy. Validate the payload shape and throw when the caller lacks permission. A validator returning false injects false; it does not deny access.

Choose where to customize

Before exposing the route, check a missing token, an invalid token, and a valid token without the required permission—not only the successful request. See authentication basics for the complete pipeline.

Documentation sections

• Authentication Basics - Authentication flow, sources, verifiers, and validators
• Token Handling - Token generation and validation functions
• Parameter Decoration - Authentication decorators and custom providers