Introduction

@eienjs/adonisjs-simple-auth provides a straightforward, database-free authentication mechanism for AdonisJS v7 applications using a single static API key passed via an HTTP request header.

It is ideal for internal microservices, webhooks, private APIs, or prototypes where a full user and token management system is unnecessary. Clients can authenticate requests easily using cURL, interactive API documentation, or standard HTTP clients.

Key Features

• Zero Database Overhead: Validates requests against a single configured API key stored in your environment variables.
• Timing-Safe Comparison: Uses AdonisJS safeEqual and Secret helpers to prevent timing attacks and accidental secret leaks in logs.
• Built-in Ace Command: Generates cryptographically secure tokens prefixed with oat_ and suffixed with a CRC32 checksum for secret scanning compatibility.
• Route Middleware: Automatically publishes a ready-to-use apiKey named middleware and augments HttpContext with ctx.simpleAuth.
• Content-Negotiated Exceptions: Handles unauthorized requests with 401 Unauthorized responses formatted for JSON, HTML, or JSON:API, with built-in @adonisjs/i18n support.
• Japa API Client Plugin: Provides a .withApiKey() macro for seamless functional testing with @japa/api-client.

Requirements

Before installing @eienjs/adonisjs-simple-auth, make sure your environment meets the following requirements:

Next Steps

Ready to add API key protection to your application? Proceed to the Installation guide to install and configure the package.