README

A framework-independent PHP CLI tool that turns API authentication failures into clear findings and safe, actionable recommendations.

It helps diagnose common 401 Unauthorized and 403 Forbidden responses without exposing credentials in diagnostic output.

Client presentation

View client presentation (PDF) | Download editable PowerPoint

What it diagnoses

Missing, empty, malformed, expired, or revoked Bearer tokens
Missing or invalid API keys
Basic authentication formatting and credential issues
Custom authentication-header problems
Conflicting authentication mechanisms in one request
HTTP 401 and 403 failures
Common permission, scope, role, network, and policy causes

Security first

Credentials are sanitized before they appear in diagnostic results. Use only fake, redacted, or safely sourced values when running diagnostics. Never commit real tokens, API keys, passwords, or production request captures.

Requirements

PHP 8.2 or later
Composer

Installation

composer install

Quick start

Diagnose a 401 response where no credentials were attached:

php bin/api-auth-debug --url=https://api.example.test/v1/profile --status=401

Example output:

{
    "authentication_type": "none",
    "http_status_code": 401,
    "successful": false,
    "findings": [
        "The server returned HTTP 401 and no authentication credentials were found in the request."
    ],
    "recommendations": [
        "Attach the credential using the authentication scheme and request location required by the API."
    ]
}

Usage

php bin/api-auth-debug --url=<url> [options]

Option	Description
`--method=<method>`	HTTP method; defaults to `GET`
`--status=<code>`	HTTP response status code
`--header="Name: Value"`	Request header; may be repeated
`--help`	Show usage information

Bearer token example

php bin/api-auth-debug --url=https://api.example.test/v1/profile --status=401 --header="Authorization: Bearer example-token"

API-key example

php bin/api-auth-debug --url=https://api.example.test/v1/orders --status=403 --header="X-API-Key: example-key"

The output is JSON, making it suitable for local troubleshooting, scripts, CI logs, or a future web interface.

Exit codes

Code	Meaning
`0`	The request has no diagnostic failure
`1`	Invalid command input or an application error
`2`	A diagnostic failure was found

Development checks

./vendor/bin/phpunit
./vendor/bin/phpstan analyse
./vendor/bin/php-cs-fixer fix --dry-run

Project status

The core diagnostic engine and CLI are complete. Current work focuses on documentation, CI automation, and portfolio-ready release polish.

License

This project is licensed under the MIT License.

sharadkashyap / php-api-authentication-debugger

Maintainers

Package info

Statistics

Security