How does the PHP SDK authenticate, and which API key permissions do I need?
I am wiring the PHP SDK into a service that also identifies logged-in users, so I want the credentials right before this ships rather than after.
My assumptions so far: the SDK authenticates with some kind of key, and since we call from the backend that key lives in server config, not in the browser. What I am not sure about is whether the key needs any particular permission given that we also identify users, and how failures surface if I get the credential wrong.
Can someone confirm how the SDK authenticates and what permission the key needs?
2 answers
Your assumptions are right. The server-side SDK authenticates with an API key, sent as the X-Api-Key header to the Croct HTTP API at api.croct.io. The key belongs in server-side config and never reaches the client. See API key authentication for the header and setup.
You create the key with the CLI:
npx croct@latest create api-keyThe permission detail matters for your case. Because your backend issues user tokens for identified users, the key needs the "Issue user tokens" permission. A key without it authenticates fine for plain content fetches but fails the moment you try to identify a user, which is a common gotcha. The key permissions page lists what each one grants.
On failures: errors come back as RFC 9457 problem+json. A bad or missing key surfaces as an invalid credentials problem response, so you can branch on the structured error rather than parsing a string.
Confirming the permission bit from experience. We had content fetches working and thought auth was done, then identify calls started failing once we shipped the logged-in path. The missing piece was exactly the "Issue user tokens" permission on the key. Once we recreated it with that, the identified-user flow went through. Set it before you ship and you skip the head-scratching we did.