Generating API Keys
@eienjs/adonisjs-simple-auth ships with a built-in generate:api-key Ace command that generates a cryptographically secure API key and stores it in your .env file.
Basic Usage
Run the following command in your project root:
node ace generate:api-key
In non-production environments (NODE_ENV !== 'production'), this command creates or updates the API_KEY variable inside your .env file:
API_KEY=oat_YWI.dXNlcl9zZWVkX2V4YW1wbGVfNDBfY2hhcnNfMTIzNDU2Nzg5MDEyMzQ1Ng
Command Flags
You can customize the behavior of generate:api-key with the following flags:
| Flag | Type | Description |
|---|---|---|
--show | boolean | Display the generated token in the terminal instead of writing it to the .env file. |
--force | boolean | Force updating the .env file when running in a production environment. |
Displaying the Key Without Modifying .env
Use the --show flag when you want to generate a key and copy it manually (for example, to paste into a cloud secret manager or CI/CD variables):
node ace generate:api-key --show
Output:
API_KEY = oat_YWI.dXNlcl9zZWVkX2V4YW1wbGVfNDBfY2hhcnNfMTIzNDU2Nzg5MDEyMzQ1Ng
Running in Production
By default, when NODE_ENV=production, generate:api-key will not modify the .env file and instead prints the generated key to the terminal. To explicitly write the key to .env in production, pass --force:
NODE_ENV=production node ace generate:api-key --force
--show and --force are passed, --show takes precedence and the key is only printed to the terminal.Token Format & Checksum
Tokens generated by node ace generate:api-key follow the same structural principles as AdonisJS opaque access tokens:
oat_<prefix>.<payload>
oat_prefix: Identifies the string as an opaque access token.<prefix>: Base64 URL-encoded 2-character random string.<payload>: Base64 URL-encoded string combining a 40-character cryptographically random seed with its CRC32 checksum.
CRC32 checksum at the end of the token payload allows secret scanning tools (such as GitHub Secret Scanning) to reliably identify leaked tokens with minimal false positives.Next, learn how to require this API key on your HTTP routes in Protecting Routes.