What is the body 'token' param used for in token introspection?

[corepay]

In the docs Token Introspection the request params are shown as:

However in your cURL sample below this you show a 'token' body param also:

What is the token param and where do I get it or do I need it or want it if optional?

[dakshitha]

The introspection endpoint is designed for clients—usually APIs—to verify the validity of an access token, whether opaque or JWT, that they receive. This typically occurs after a user logs in and attempts to access a backend API with the token issued for the logged in user or it could be a token issued to a machine user such as a CLI or a backend system that cannot perform a login via a browser. Before granting access, the API must confirm that the token is still valid and hasn't been revoked, by querying the introspection endpoint. When sending an introspection request, the API (or CLI in this case) must also include a client assertion—a JWT signed with a previously downloaded private key under the JWT profile (not needed if it's not JWT profile)—to prove its registered client status. This ensures only authorized clients can perform token introspection. So, the token you see here has to come from a front end or it could be a token issued to a service or machine user such as a Personal Access Token (PAT) in ZITADEL.

You can get more insight on this topic by reading this blog post - https://zitadel.com/blog/api-access-and-introspection#31-jwt-profile

[corepay]

Yes thank you

but...you linked me back to the link I gave you asking what the token param is used for in the cURL example becuase there is not mention of this param in that page nor anywhere else I can find. So I suggest putting an explanation in the docs what the token value is used for during an introspection call or remove it from the cURL example.

I am trying to help you guys :)

[corepay]

What still confuses me is th following scenario:

1. I have a PAT for an ADMIN api I use to communicate with Zitadel. Lets call the PAT value 123
2. I have an API request to my server API from a developer who puts their already issued token in the header Authorization. Lets call the token value ABC

So I need to / want to introspect this developer token. This value should be in the client_assertion value and my PAT should be in the token value like this?

curl --request POST \
 --url {your_domain}/oauth/v2/introspect \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
 --data client_assertion=ABC \<--developer token making the request Authorization header
 --data token=123. <-- My server Admin Personal Access token

[corepay]

• NOTE - the developer is making a request to MY server APIs - not Zitadel..no one in my setup but my servers will access Ziadel directly.