Use Zitadel from Retool

Hi all, looking for some guidance on how to integrate Zitadel OAuth2 with a Retool app.

Retool allows you to use OAuth 2 compliant endpoints as resources, and say they will handle all the complexity of managing the OAuth2 flows on behalf of the user. Basically, user logs in to retool, then starts an app. While using the app, different resources including OAuth2 compliant resource providers are used to retrieve data that is served to the user. Retool as the middleman caches tokens (both access and refresh) on behalf of the user, and uses them when making queries.

my base setup:

a project (TEST-PROJECT)
A Web app for the user interface (TEST-APP)
2.a App uses JWT token
2.b has refresh token
2.c Added Retool URI to redirect/post logout URI's
An API app to represent the resource provider (TEST-PROVIDER)

This basically works, but Retool doesn't know how to validate the token and direct the user to Zitadels login flow when it's not valid. I can set the settings on Retool to allow refresh/verification, but here's where I get confused.

I am using the introspection endpoint for verification,
```
/oauth/v2/introspect
```
/oauth/v2/introspect
```
/oauth/v2/introspect
```
/oauth/v2/introspect
I need a static client Id and Client Secret to be used by Retool when calling the introspect endpoint. I'm not sure how to configure that, while still allowing the user to use a user specific JWT token.

My starting attempt was to create a second API APP for Retool, which then has a id & secret configured, and provide that to Retool. However, when I test authentication using that setup Zitadel responds with an "Invalid_request" "Errors.App.NotFound" response instead of redirecting back to Retool.

scopes: openId profile email offline_access urn:zitadel:iam:org:project🆔XXXXXXXXXXXXXX:aud

scopes: openId profile email offline_access urn:zitadel:iam:org:project🆔XXXXXXXXXXXXXX:aud

scopes: openId profile email offline_access urn:zitadel:iam:org:project🆔XXXXXXXXXXXXXX:aud

scopes: openId profile email offline_access urn:zitadel:iam:org:project🆔XXXXXXXXXXXXXX:aud

Does anyone else have experience using Retool and Zitadel? Or is this familiar from someone elses use case?

Ask Inkeep•12/9/25, 1:24 PM

Hi @staevid, 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•12/9/25, 1:24 PM

Answer

Introspection Setup for Retool

Your approach of creating a separate API app for introspection is correct. The introspection endpoint requires its own client credentials to authenticate the calling application (Retool) , which is separate from the user's access token being validated. (1)

Key Points:

Introspection endpoint: ${CUSTOM_DOMAIN}/oauth/v2/introspect${CUSTOM_DOMAIN}/oauth/v2/introspect
Authentication methods for introspection: You can use either client_secret_basicclient_secret_basic or private_key_jwtprivate_key_jwt to authenticate the introspection request.

For client_secret_basicclient_secret_basic, send credentials as a Basic Auth header:

curl --request POST \
  --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {your_basic_auth_header}' \
  --data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...

curl --request POST \
  --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {your_basic_auth_header}' \
  --data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...

The Basic Auth header format is: (2)

Authorization: "Basic " + base64( formUrlEncode(client_id) + ":" + formUrlEncode(client_secret) )

Authorization: "Basic " + base64( formUrlEncode(client_id) + ":" + formUrlEncode(client_secret) )

Ask Inkeep•12/9/25, 1:24 PM

Regarding the "Errors.App.NotFound" Error:

This error suggests the client_id being used doesn't match a registered application. Ensure:

The API app is created within the same project
You're using the correct client_id from that API app

### Important Scope Consideration:

For introspection to return active: trueactive: true, the token must include the project's audience scope. Your scope urn:zitadel:iam:org:project🆔XXXXXXXXXXXXXX:audurn:zitadel:iam:org:project🆔XXXXXXXXXXXXXX:aud is correct for this purpose. (3)

Note: Every app needs its own credentials for introspection, and it's project-specific—the introspecting application must be part of the token's audience. (4)

Check out these potentially useful sources: OpenID Connect Endpoints in ZITADEL , Authentication Methods in ZITADEL

If this doesn't resolve your issue, click the "Ask for help" button to have a team member review your question.

Ask Inkeep•12/9/25, 1:24 PM

To learn more, see the sources I considered:

[1] OpenID Connect Endpoints in ZITADEL
[2] Authentication Methods in ZITADEL
[3] Discord message from @aver.develop on 2024-05-23
[4] Discord message from @leogalante7032 on 2025-10-23

Ask Inkeep•12/9/25, 1:24 PM

Feel free to tag @Ask Inkeep with additional questions.

AAsk Inkeep To learn more, see the sources I considered: [[1] OpenID Connect Endpoints in...

Ask InkeepAPP•12/9/25, 1:39 PM

Got it. Tagging @Rajat for additional help.

staevidOP•12/9/25, 1:40 PM

I read the above automated response, but that didn't resolve anything. I can't get to the underlying implementation in Retool, but based on what I'm seeing it should be able to handle the basic authentication just fine.

Rajat•12/10/25, 11:05 AM

hey @staevid thanks for your question, I have not heard about retool so I will take a look and will get back to you, for now, I can just say that invalid_requestinvalid_request that probably means that the Client ID you are providing for the introspection call is not recognized by ZITADEL as a valid client.

staevidOP•12/10/25, 1:37 PM

Thanks @Rajat for looking in to it. The client ID is associated with an app within the project, and which is an API app. That app does have a client secret. Would it return an AppNotFound if the combination of ID and secret were incorrect?

Sstaevid Thanks <@1346540274674827395> for looking in to it. The client ID is associated...

Rajat•12/10/25, 2:37 PM

The error Errors.App.NotFoundErrors.App.NotFound means zitadel cannot locate an application matching the Client ID you are sending in the Basic Auth header.

For introspection: Use the API App client ID(screenshot attached) + secret that you will generate.

staevidOP•12/10/25, 8:25 PM

Yeah, that is what I’m using. I’ll double check that the secret is correct, but as far as I can tell everything should be aligned. I’ll check the configurations again and validate.