feat(api): GET /v1/whoami — identity probe for SDK clients#63
Merged
Conversation
Lightweight diagnostic endpoint. SDK clients (or curious operators)
can hit /v1/whoami and learn what their authKey resolves to
without firing a domain call and inferring from 403/200 patterns.
Response shape:
{
"authenticated": bool,
"isMaster": bool,
"companyId": int | null
}
Three documented states:
- master key: {true, true, null}
- scoped key: {true, false, <compId>}
- unknown key: {false, false, null} (200, not 403)
The 200-vs-403 split is deliberate: a missing authKey header
returns 403 (the client never sent credentials), but a present
header with an unrecognized key returns 200 with
`authenticated: false` so the client can distinguish "network
plumbing wrong" from "credential wrong" without parsing error
messages.
Tests: 4 cases covering the auth contract (403 without header),
route mounting, the DB-unreachable fallback path (which under
test env's broken DB happens to produce the documented unknown-
key shape — so we test the public contract there), and response
shape invariants.
OpenAPI spec gets the path + response schema. Suite: 31 files /
227 passing + 4 integration skipped (was 30 / 223 + 4 skipped).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
GET /v1/whoami— clients can hit this to learn whether their authKey is recognized, whether it's a master key, and which company it scopes to. Avoids the current pattern of "hit /v1/customer/1 with my key, infer from 403/200/404 what my permissions are."Response shape:
{ "authenticated": true, "isMaster": false, "companyId": 42 }Three states: master / scoped / unknown. Unknown is 200 with
authenticated: false(not 403), so a client can distinguish "header missing" from "header present but credential wrong."Test plan
Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/