History of gotchas/first-access-token-response-exposure.md

@@ -0,0 +1,13 @@+# Never return raw first-access tokens from partner-creation responses++First-access tokens are onboarding credentials and must not be included in the HTTP response of a partner-creation endpoint. Returning `rawToken` lets a caller with partner-creation permission capture the credential and complete password setup without receiving the intended welcome email.++## Safe flow++- Generate the raw token only inside the application service.+- Persist its SHA-256 hash, never the raw value.+- Send the raw token only through the dedicated first-access notification.+- Return only non-secret metadata such as the created partner ID.+- Test both that the response excludes the token and that the email still contains it.++This keeps the API response from becoming an alternate credential-delivery channel.