docs: the authentication example returns 405, and returns it for a bad key too #39

Page or section

Authentication, the "Authorization header" section.

Problem

The example that shows how to send your key is a GET to /v1/calls:

curl https://api.heycall-e.com/v1/calls \
  -H "Authorization: Bearer $CALLE_API_KEY" \
  -H "Content-Type: application/json"

That path only has post in openapi/calle.openapi.yaml, so the request comes back:

HTTP 405
Method Not Allowed

I ran it again with a key I made up on the spot. Also 405, byte for byte the same.

So the one example a developer reaches for on their first afternoon does not work, and worse, it cannot tell a working key from a broken one. Both answers are identical. Someone whose key really is wrong will read that 405, assume the key is fine and go hunting somewhere else.

It is the first page in the docs where anything is actually run, which is a rough place to lose people.

Suggested improvement

Swap it for a request that reaches an endpoint the key can be checked against. A read of a call id that cannot exist works nicely, because a 404 back is proof the key was accepted and nothing was created:

curl -i https://api.heycall-e.com/v1/calls/call_does_not_exist \
  -H "Authorization: Bearer $CALLE_API_KEY"

404 means the key is good. 401 or 403 means it is not. Two outcomes, and they mean different things.

Worth saying on the page which status means which, since telling those apart is the entire reason somebody runs the command.