Skip to main content
InferenceWall authenticates requests using API keys with two distinct roles: scan for scanning and analysis endpoints, and admin for management and configuration endpoints. You pass the key in the Authorization header of every request.

​
Dev mode

If the IW_API_KEY environment variable is not set, authentication is disabled entirely. This is convenient for local development, but you must enable auth before deploying to production.

​
Generating keys

Run the setup command to generate both a scan key and an admin key: 
inferwall admin setup
This writes the generated keys to .env.local in your working directory. Source the file to load them into your environment: 
source .env.local
Keys use the following format:
Key typePrefixExample
Scaniwk_scan_iwk_scan_a1b2c3d4e5f6...
Adminiwk_admin_iwk_admin_a1b2c3d4e5f6...

​
Passing the key

Include your API key in the Authorization: Bearer header on every request: 
curl -X POST http://localhost:8000/v1/scan/input \
  -H "Authorization: Bearer iwk_scan_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "user input"}'

​
Key roles

Each key type grants access to a specific set of endpoints:
Key typePrefixCan access
Scaniwk_scan_/v1/scan/*, /v1/analyze/*, /v1/health/*, /v1/signatures (read-only), /v1/sessions
Adminiwk_admin_All endpoints, including /v1/admin/*, /v1/auth/*, /v1/config, and all scan endpoints
Use the scan key in your application code. Reserve the admin key for management scripts and CI pipelines.

​
Auth endpoints

​
POST /v1/auth/login

Log in with your admin key. On success, InferenceWall sets an httpOnly session cookie that you can use for subsequent requests. Request body:
​
key
string
required
Your admin API key (iwk_admin_ prefix).
curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"key": "iwk_admin_YOUR_KEY"}'

​
POST /v1/auth/logout

Clear the current session cookie. 
curl -X POST http://localhost:8000/v1/auth/logout

​
GET /v1/auth/check

Check whether the current session cookie is valid. 
curl http://localhost:8000/v1/auth/check

​
Error responses

When a request is made without a valid key or session, the API returns 401 Unauthorized: 
{
  "detail": "Unauthorized"
}

​
Security best practices

Never commit API keys to source control. Use environment variables or a secrets manager.
  • Enable TLS in production by setting IW_TLS=auto. This uses automatic certificate management via ACME.
  • Rotate keys regularly and revoke any that are no longer in use.
  • Scope your application’s key to the minimum required role — use iwk_scan_ keys in application code and reserve iwk_admin_ keys for management operations.