[albertoelias-crossmint]

fix(server-sdk): throw with the HTTP status when a server auth call fails

Problem

A developer calls crossmintAuth.getUser(userId) from the server SDK with a server API key that does not have the users.read scope. Crossmint answers 403 with The API key provided doesn't have the required scopes to perform this action: users.read. The SDK does not look at the status: it returns that error body as if it were the user. The developer gets { statusCode: 403, message: "...", error: "Forbidden" } where user.email should be, and finds out only when the code reading user.email misbehaves.

Failed session refreshes and logouts have the same shape: a refresh that Crossmint rejects with Invalid refresh token surfaces only as the HTTP status text (Unauthorized), and a failed logout is ignored without a trace. Nothing says which scope an API key needs.

What this PR does

• getUser throws a CrossmintAuthenticationError when Crossmint rejects the request. The error has status and the API's own message; on 401 or 403 it adds that getUser needs a server API key with users.read.
• getUser returns SDKExternalUser instead of any, and encodes the user ID in the request path.
• Failed refreshes (default and custom route) and logouts report the status and the API's message.
• The server SDK exports CrossmintAuthenticationError and SDKExternalUser.
• README: a scopes table and a getUser example that handles the error.

flowchart LR
  subgraph Before
    A1[getUser, key without users.read] --> B1[API 403] --> C1[error body returned as the user]
  end
  subgraph After
    A2[getUser, key without users.read] --> B2[API 403] --> C2[throws CrossmintAuthenticationError, status 403, names users.read]
  end

Loading

Result

	Before	After
getUser with a key lacking users.read	returns { statusCode: 403, message, error }	throws Failed to get user (403: ...users.read...). getUser needs a server API key with the users.read scope
getUser for an unknown user	returns the 404 body	throws Failed to get user (404: User with id ... not found.), error.status === 404
Rejected refresh token	Unauthorized	Failed to refresh the session (401: Invalid refresh token)
Return type of getUser	any	SDKExternalUser

Unchanged: successful getUser, getSession and logout behaviour (logout still clears the cookies and does not throw; a failed revoke call is logged with its status).

What to check when reviewing

• packages/common/auth/src/utils/authErrorFromResponse.ts: message format <action> (<status>: <API message>), API message from message or error, status text as fallback.
• getUser callers that relied on getting a body back for non-2xx responses now see a throw. That is the intended fix, but it is a behaviour change for anyone who checked user.error.
• getUser now returns SDKExternalUser instead of any. TypeScript callers that read fields outside that type will get a compile error.
• getSession still reports Failed to get session to its caller (the cause is logged); only getUser and handleCustomRefresh expose the status in the response.
• Overlap: fix(server-sdk): read and write the project-scoped auth cookies #2277 edits CrossmintAuthServer.ts, its test and packages/server/README.md; whichever merges second takes the other's change (different methods and README sections).

Test plan

• pnpm --filter @crossmint/server-sdk test:vitest: 70 passed. @crossmint/common-sdk-auth: 8 passed.
• Builds: common-sdk-auth and server-sdk.
• New tests fail on the old code: reverting getUser fails the 403, 404 and path-encoding tests; reverting the refresh error handling fails the rejected-refresh test; the message-format table fails without the helper.
• Manual: call getUser against staging with a key without users.read.

Checklist

• Changeset: server-sdk, common-sdk-auth (patch)
• README snippet type-checks against the exported types
• Biome clean on changed files
• No Co-Authored-By lines

Rollback

Revert the PR. No data or API changes; callers go back to receiving the error body.

Closes WAL-13394

🤖 Generated with Claude Code

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 4bdbca8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 14 packages

Name	Type
@crossmint/server-sdk	Patch
@crossmint/common-sdk-auth	Patch
@crossmint/auth-ssr-nextjs-demo	Patch
crossmint-auth-node	Patch
@crossmint/client-sdk-auth	Patch
@crossmint/client-sdk-react-base	Patch
@crossmint/client-sdk-react-native-ui	Patch
@crossmint/client-sdk-react-ui	Patch
@crossmint/wallets-sdk	Patch
@crossmint/wallets-playground-expo	Patch
@crossmint/client-sdk-nextjs-starter	Patch
@crossmint/wallets-quickstart-devkit	Patch
@crossmint/wallets-playground-react	Patch
@crossmint/integration-tests	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

Devin Review found 2 potential issues.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new actionable issues remain.

_{Reviews (2) · Last reviewed commit: "Kebab-case the auth error test file and ..." · Reviewed by Greptile}

[albertoelias-crossmint]

@greptileai review