clerk / clerk/clerk-sdk-python

users.list() / users.get() raise ResponseValidationError for SAML accounts with status: "verified" — external_verification_redirect_url missing from response

Open Beginner friendly
#241 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
186
Forks
47
Avg merge
18h 43m
Merged PRs (30d)
1

Description

Description

Calling users.list() (or users.get()) on a user with a SAML account that has completed sign-in fails with a Pydantic validation error, because the VerificationSAML model requires external_verification_redirect_url, but the actual API response omits that key once the SAML verification status is "verified".

Error:

ResponseValidationError: Response validation failed: 1 validation error for Unmarshaller
body.0.saml_accounts.0.verification.verification_saml.external_verification_redirect_url
Field required [type=missing, input_value={'object': 'verification_...ttempts': None, 'expire_at': 1783093481844}, input_type=dict]

Steps to reproduce:

  1. Set up a SAML connection on an organization.
  2. Have a user complete a full SAML sign-in (not just start one) so their SAML account verification reaches status: "verified".
  3. Call GET /v1/users (or /v1/users/{id}) for that user.
  4. Attempt to unmarshal the response with the SDK — it throws instead of returning the user.

Actual API response (saml_accounts[].verification) for a verified account — note there's no external_verification_redirect_url key at all:
{
"object": "verification_saml",
"status": "verified",
"strategy": "saml",
"attempts": null,
"expire_at": 1783093481844
}

What the SDK's model expects (VerificationSAML in clerk_backend_api/models/samlaccount.py), which requires the key to be present:
{
"object": "verification_saml",
"status": "verified",
"strategy": "saml",
"external_verification_redirect_url": null,
"attempts": null,
"expire_at": 1783093481844
}

For comparison, an in-progress (not yet completed) SAML verification does include the field:
{
"object": "verification_saml",
"status": "unverified",
"strategy": "saml",
"external_verification_redirect_url": "https://accounts.example.com/v1/verify?...",
"attempts": null,
"expire_at": 1783093481844
}

Expected: Either the API always includes external_verification_redirect_url (as null when not applicable), or the SDK model marks it as optional/nullable-missing to match the API's actual behavior for verified/expired/transferable statuses.

Impact: Any call that lists/fetches a user with a completed SAML login fails entirely, even when the caller only needs unrelated fields (e.g. name, email) and never reads saml_accounts

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with VerificationSAML in clerk_backend_api/models/samlaccount.py and trace the response unmarshalling used by users.list() and users.get(). Compare the verified SAML response, which omits external_verification_redirect_url, with the in-progress response. Done means verified SAML users can be listed or fetched without a ResponseValidationError while the model still handles the field when present.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.