Auth Issues

401 Unauthorized during scan

Symptom: NAT receives 401 Unauthorized responses for most or all requests.

Solutions:

1. Verify your token is valid independently:

   curl -H "Authorization: Bearer $TOKEN" https://api.example.com/api/v1/me
2. Check token expiry — if the token expires during a long scan, use OAuth2 to enable automatic refresh
3. Ensure the auth type matches your API:

   # For Bearer tokens:
   nat scan --url ... --auth-type bearer --token "$TOKEN"
    
   # For API key in a header:
   nat scan --url ... --auth-type header --header "X-API-Key: $KEY"

403 Forbidden on some endpoints

Symptom: Some endpoints return 403 Forbidden during scanning — but your credentials work normally.

Why this happens: NAT tests endpoints with different identity contexts, including other users' tokens (if you provided --secondary-token). Some 403 responses are expected and indicate the authorization controls are working correctly.

What to check:

1. Look at which endpoints return 403 — if admin endpoints return 403 for a non-admin token, that's correct behavior
2. If your own token gets 403 on endpoints it should have access to, check whether NAT's test requests are altering session state

OAuth2 token fetch fails

Symptom: NAT exits with "Failed to fetch OAuth2 token" before the scan starts.

Solutions:

1. Test the token endpoint manually:

   curl -X POST https://auth.example.com/oauth/token \
     -d "grant_type=client_credentials" \
     -d "client_id=$CLIENT_ID" \
     -d "client_secret=$CLIENT_SECRET" \
     -d "scope=read write"

2. Common OAuth2 issues:

   Error	Solution
   invalid_client	Wrong client ID or secret
   invalid_scope	Requested scope not granted to this client
   unauthorized_client	Client not allowed to use this grant type
   invalid_grant	Token URL wrong, or for password grant: wrong username/password
   Connection error	Token URL unreachable — check network and firewall

3. For Auth0, use --oauth2-audience instead of --oauth2-scope:

   nat scan --url ... \
     --auth-type oauth2 \
     --oauth2-token-url https://YOUR_DOMAIN.auth0.com/oauth/token \
     --oauth2-client-id $CLIENT_ID \
     --oauth2-client-secret $CLIENT_SECRET \
     --oauth2-audience https://api.example.com

JWT errors

Symptom: Server responds with JWT validation errors during scan.

Common JWT issues:

Token expiry during long scans

Symptom: Scan starts successfully but fails midway with 401 errors as the token expires.

Solutions:

1. Use OAuth2 with client credentials — NAT automatically refreshes the token:

   nat scan --url ... \
     --auth-type oauth2 \
     --oauth2-token-url ... \
     --oauth2-client-id $ID \
     --oauth2-client-secret $SECRET
2. Generate a token with a longer expiry before scanning
3. Use --max-requests to limit scan size and ensure it completes before expiry

Basic auth not working

Symptom: --auth-type basic doesn't authenticate correctly.

Solutions:

1. Verify the credentials work with curl:

   curl -u "$USERNAME:$PASSWORD" https://api.example.com/api/v1/me
2. Ensure the username doesn't contain special characters that need escaping
3. Check if the API actually uses Basic auth (vs. a form login endpoint that returns a session token)

Self-hosted: API key authentication to NAT server

If you're using the self-hosted NAT server and the API key isn't working:

1. Generate a new API key from the dashboard under Settings → API Keys
2. Pass it in the Authorization header: Authorization: Bearer YOUR_KEY
3. Check the server logs for auth errors: nat server logs or docker compose logs nat-server

Next steps

• Authentication Configuration — auth setup reference
• Set Up OAuth2 — detailed OAuth2 guide
• Common Issues — general troubleshooting