Helping Developers Get Unstuck.
Authentication problems rarely arrive as neat bug reports. I spent a lot of time meeting developers in those moments. Trying to dive quickly into their world, understand what they were trying to build, and figure out where things were going wrong. The error in front of us was usually just the place to start.
Debug the implementation.
A common scenario: a developer is trying to update users through the Management API but keeps getting a 400 error
The request looked close, but something wasn't right.
Their GET request worked, but PATCH kept failing. That gave me somewhere to start.
PATCH /api/v2/users/123
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"name": "Kim"
}
→ 400 Bad Request
I compared the two requests, checked how the API was being called, and narrowed the problem down
to the request itself.
There were two issues two issues hiding in the request. The request was using 1) an incorrect endpoint and 2)
the header wasn't being passed correctly. Once both were fixed, the PATCH request worked.
Explain what’s happening.
Not every problem came down to broken code. Another common scenario is when a dev is requesting
additional user information when getting a token, but the token coming back doesn't contain
everything they had asked for.
From their perspective, the request had worked. They had a token.
The confusing part was why some of the information they requested
wasn't there.
openid name email app_metadata identities
openid email
The answer came down to how OpenID Connect (OIDC) handles claims. OIDC defines a set of standard
claims that can be included in an ID token. app_metadata is not
one of them. So asking for it in the scope isn't enough.
I would walk developers through how OIDC claims worked, then show them how to explicitly add the
information they needed as a custom namespaced claim.
var namespace = 'https://example.com/';
context.idToken[namespace + 'app_metadata'] =
user.app_metadata;The metadata could then be included in the ID token under its own namespace, avoiding collisions with standard OpenID Connect claims.
Take the problem back to the product
There were also times when digging into a developer's problem exposed
friction in the product itself.
One developer couldn't create a Rule using the name they wanted.
Nothing about the error made it obvious why, so I tried to reproduce
the problem myself.
example@rule
example@rule
examplerule
The code hadn't changed. The @ in the Rule name
was the problem.
I eventually found the answer buried in the documentation.
There were restrictions on how Rules could be named, but the developer
had very little chance of discovering that from the experience in
front of them.
I could explain the restriction and get them moving again. I also
took the issue back to the team. If one developer had run into it,
there was a good chance someone else would too.
Look for the problem behind the problem
After enough conversations like these, I learned not to take the error
in front of me at face value.
A failed API call might come down to the request itself. Missing information
might mean digging into how the underlying protocol works. An error pointing
at someone's code might turn out to be friction in the product.
The useful part wasn't knowing every answer. It was knowing where to start
looking, asking enough questions to understand what someone was trying to
build, and staying with the problem until we understood what was happening.
Those conversations also gave me a clearer view into where developers were
getting stuck. When the same questions or points of confusion kept appearing,
that was useful information to take back to the teams building the product,
documentation, and developer experience.