What causes "CIMD document must specify private_key_jwt auth method" in PrefectHQ/fastmcp?

Update the CIMD document to set `token_endpoint_auth_method: "private_key_jwt"` if that is the intended method

PrefectHQ/fastmcp · error · ValueError

CIMD document must specify private_key_jwt auth method

Error message

CIMD document must specify private_key_jwt auth method

What it means

The client has a CIMD document, but that document's `token_endpoint_auth_method` is not `"private_key_jwt"`. The library refuses to validate a private_key_jwt assertion against metadata that declares a different authentication method.

Source

Thrown at fastmcp_slim/fastmcp/server/auth/cimd.py:821

        """Validate JWT assertion for private_key_jwt auth.

        Args:
            assertion: JWT assertion string from client
            client: OAuth proxy client (must have cimd_document)
            token_endpoint: Token endpoint URL for aud validation

        Returns:
            True if assertion is valid

        Raises:
            ValueError: If client doesn't have CIMD document or validation fails
        """
        if not hasattr(client, "cimd_document") or not client.cimd_document:
            raise ValueError("Client must have CIMD document for private_key_jwt")

        cimd_doc = client.cimd_document
        if cimd_doc.token_endpoint_auth_method != "private_key_jwt":
            raise ValueError("CIMD document must specify private_key_jwt auth method")

        return await self._assertion_validator.validate_assertion(
            assertion, client.client_id, token_endpoint, cimd_doc
        )

View on GitHub (pinned to 1f02114297)

Solutions

Update the CIMD document to set `token_endpoint_auth_method: "private_key_jwt"` if that is the intended method
Alternatively, change the client to use the auth method declared in its CIMD document
Redeploy/refresh the metadata so the cached CIMD document reflects the corrected method

Example fix

// before (CIMD document)
{"token_endpoint_auth_method": "client_secret_post", ...}
// after
{"token_endpoint_auth_method": "private_key_jwt", "jwks": {"keys": [...]} }

Defensive patterns

Strategy: validation

Validate before calling

doc = client.cimd_document
if doc.token_endpoint_auth_method != "private_key_jwt":
    raise RuntimeError(f"CIMD doc declares {doc.token_endpoint_auth_method!r}; client uses private_key_jwt")

Type guard

def supports_private_key_jwt(doc) -> bool:
    return getattr(doc, "token_endpoint_auth_method", None) == "private_key_jwt"

Try / catch

try:
    await manager.validate_private_key_jwt(assertion, client, endpoint)
except ValueError as e:
    if "must specify private_key_jwt" in str(e):
        logger.error("Auth method mismatch between client request and CIMD metadata")
    raise

Prevention

Keep the client's token request auth method in sync with its published CIMD metadata
Re-check the CIMD document whenever the client's auth configuration changes
Test end-to-end after editing the metadata document (caches may serve stale values)
Declare `token_endpoint_auth_method: "private_key_jwt"` explicitly, don't rely on defaults

When it happens

Trigger: `validate_private_key_jwt` is called (via `authenticate_request`) with a client whose CIMD metadata declares e.g. `client_secret_basic`, `client_secret_post`, `none`, or `self_signed_tls_client_auth` while the token request uses private_key_jwt.

Common situations: Mismatch between what the client developer implemented and what the published CIMD document declares; the CIMD document was updated (method changed) but the client still sends private_key_jwt; a copy-pasted metadata file with the wrong auth method.

Related errors

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/3aa78ee0f36090ff. Report an issue: GitHub.