✌

Need help with "private-key-jwt"

Hey folks, I was evaluating Zitadel for my SAAS solution. I needed some help regarding the API application under my project.
I was following the steps in this link from the documentation:
https://zitadel.com/docs/guides/integrate/token-introspection/private-key-jwt
I created an API application under my project and selected "Private Key JWT" for authorisation. I generated the JWT based on the key, keyId and clientId that I found in a JSON file, which was downloaded when I created a key under that API application. I hit this URL
"https://********.zitadel.cloud/oauth/v2/introspect" from "https://hoppscotch.io/"
I am getting 500 every time, with this message body:
{
"error": "invalid_client",
"error_description": "client must be authenticated"
}
I am confused about how I can solve this problem. I intend to use the Zitadel API to get some data, like roles and some other info, to my web API backend.

ZITADEL Docs

This is a guide on how to secure your API using JSON Web Token (JWT) profile (recommended).

Hoppscotch • Open source API development ecosystem

Helps you create requests faster, saving precious time on development.

Ask Inkeep•10/23/25, 11:25 AM

Hi @

mns

, I'm an AI assistant for ZITADEL. While a team member reviews this question, I'll see if I can find relevant sources for your question.

Ask Inkeep•10/23/25, 11:25 AM

Answer

I wasn't able to find a direct answer, here are some relevant sources:

Configure private key JWT authentication for service users (1) : This shows the proper JWT structure and token endpoint usage for private key JWT authentication with service users.
[Bug]: Token endpoint returns 500 for Private Key JWT using API application type (not service user) (2) : This GitHub issue describes the exact same problem you're experiencing - a 500 error when using Private Key JWT with API application types instead of service users.

Ask Inkeep•10/23/25, 11:25 AM

To learn more, see the sources I considered:

[1] Configure private key JWT authentication for service users
[2] [Bug]: Token endpoint returns 500 for Private Key JWT using API application type (not service user)

Ask Inkeep•10/23/25, 11:25 AM

Feel free to tag @Ask Inkeep with additional questions.

AAsk Inkeep To learn more, see the sources I considered: [[1] Configure private key JWT a...

Ask InkeepAPP•10/23/25, 11:29 AM

Got it. Tagging @Rajat for additional help.

✌

✌mns✌OP•10/23/25, 11:32 AM

I have been through every single link that @Ask Inkeep shared before I came here to post. All the GitHub issues are open.

Ask Inkeep•10/23/25, 11:32 AM

Thanks for the follow-up, @

mns

. I'll get back to you soon.

Ask Inkeep•10/23/25, 11:32 AM

Answer

Based on the available sources, the issue you're encountering is a known limitation. API applications currently cannot authenticate themselves using Private Key JWT - this functionality is only available for service users (1) .

The solution is to use a Service User instead of an API application for your use case (2) . Here's what you need to do:

Create a Service User instead of an API application (3)
Generate a private key for the service user
Create and sign a JWT with the proper structure

For the JWT structure, you need these specific claims :

Header:

{
  "alg": "RS256",
  "kid": "100509901696068329"
}

{
  "alg": "RS256",
  "kid": "100509901696068329"
}

Payload:

{
  "iss": "100507859606888466",
  "sub": "100507859606888466", 
  "aud": "<https://$CUSTOM-DOMAIN%22,>
  "iat": [Current UTC timestamp],
  "exp": [UTC timestamp]
}

{
  "iss": "100507859606888466",
  "sub": "100507859606888466", 
  "aud": "<https://$CUSTOM-DOMAIN%22,>
  "iat": [Current UTC timestamp],
  "exp": [UTC timestamp]
}

Then make your token request to the

/oauth/v2/token

/oauth/v2/token

endpoint, not the introspect endpoint :

curl --request POST \
  --url https:/$CUSTOM-DOMAIN/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data scope='openid' \
  --data assertion=[YOUR_SIGNED_JWT]

curl --request POST \
  --url https:/$CUSTOM-DOMAIN/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data scope='openid' \
  --data assertion=[YOUR_SIGNED_JWT]

To access ZITADEL APIs, include the scope

urn:zitadel:iam:org:project🆔zitadel:aud

urn:zitadel:iam:org:project🆔zitadel:aud

in your token request (2) .

The GitHub issue you referenced confirms that API applications returning a 500 error for Private Key JWT is a known bug, but the workaround is to use Service Users instead (1) .

Ask Inkeep•10/23/25, 11:32 AM

To learn more, see the sources I considered:

[1] [Bug]: Token endpoint returns 500 for Private Key JWT using API application type (not service user)
[2] Authenticate service users and client applications
[3] Configure private key JWT authentication for service users

Ask Inkeep•10/23/25, 11:32 AM

Feel free to tag @Ask Inkeep with additional questions.

curl --request POST \ --url https:/$CUSTOM-DOMAIN/oauth/v2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \ --data scope='openid' \ --data assertion=[YOUR_SIGNED_JWT]