How to correctly use the introspection endpoint with identity server 4?

Introspection is typically used by APIs to validate an incoming token. Also the introspection endpoint requires authentication per spec.

You need to setup an API secret:

https://identityserver4.readthedocs.io/en/latest/reference/api_resource.html

And then use the api name/secret to authenticate against the introspection endpoint. Either using Basic authentication or posting the values in the form.

@Jay's answer above helped me a lot. In my case I had forgotten to change content type to url-encoded as per the RFC 7662 i.e.

r.Header.Add("Content-Type", "application/x-www-form-urlencoded")

The implementation of IdSvr4 is fantastic, but the docs leave a lot to be desired - I spent a good hour searching on the internet to be able to come up with a working solution. Being told to 'read the spec' just isn't always helpful if you are new to a concept - which is something that happens alot on their forums.

So - what you have to pass to the POST /connect/introspect is a scope secret.

You can configure the quickstarts by changing the config.cs class. You will need to update whatever datastore you use if you have customised it, or are not using the quickstart - but the concept should (hopefully) be clear.

public static IEnumerable<ApiResource> GetApiResources()
{
    return new List<ApiResource>
    {
        new ApiResource("MyResource", "My_Resource_DisplayName")
        {
            ApiSecrets = new List<Secret>
            {
                new Secret("hello".Sha256())
            },
            Scopes=
            {
                new Scope("MY_CUSTOM_SCOPE")
            }
        }
    };
}

Now...

1. Ensure that your client has the scope MY_CUSTOM_SCOPE
2. Ensure you have requested the scope MY_CUSTOM_SCOPE when getting a bearer token.

Now, make a Base64 encoded string of the api resource name and secret like this:

Convert.ToBase64String(Encoding.UTF8.GetBytes(string.Format("{0}:{1}", userName, password)));

Where username is MyResource and password is plaintext hello (obv. use your own values!) - should end up with a string which looks like this: TXlSZXNvdXJjZTpoZWxsbw==

Now, you can post to IDSvr4...

POST /connect/introspect
Authorization: Basic TXlSZXNvdXJjZTpoZWxsbw==
Accept: application/json
Content-Type: application/x-www-form-urlencoded

token=<YOUR_TOKEN>

So, as long as your bearer token has the scope MY_CUSTOM_SCOPE (or whatever you ended up calling it) - you should now be able to use to introspection endpoint of IdSvr to get info about it.