Skip to main content

Troubleshoot ZITADEL

You will find some possible error messages here, what the problem is and what some possible solutions can be.

Didn't find an answer?

Join or Chat or open a Discussion.

User agent does not correspond

This error appeared for some users as soon as they were redirected to the login page of ZITADEL. ZITADEL uses some cookies to identify the browser/user agent of the user, so it is able to store the active user sessions. By blocking the cookies the functions of ZITADEL will be affected.

We only found this issue with iPhone users, and it was dependent on the settings of the device.

Go to the settings of the app Safari and check in the "Experimental WebKit Features" if SameSite strict enforcement (ITP) is disabled Also check if "block all cookies" is active. If so please disable this setting.

To make sure, that your new settings will trigger, please restart your mobile phone and try it again.

Settings > Safari > Advanced > Experimental Features > disable: „SameSite strict enforcement (ITP)“

Same Site Strict Enforvement

Settings > Safari > disable: "Block All cookies" Block all cookies

Do you still face this issue? Please contact us, and we will help you find out what the problem is.

Invalid audience

invalid audience (APP-Zxfako)

This error message refers to the audience claim (aud) of your token. This claim identifies the audience, i.e. the resource server, that this token is intended for. If a resource server does not identify itself with a value in the "aud" claim when this claim is present, then the must be rejected (see RFC7519 for more details).

You might encounter this error message from ZITADEL, typically when you authenticated with a client in one project and trying to access an application in another project. You need add a specific reserved scope to add the projectID to the audience of the access token.

The two scenarios should help you troubleshoot this issue:

Frontend to Backend

You have one project for your frontend application and one project for your backend application. End-users authenticate to an application in your frontend project. The frontend then sends requests to the backend, validates the token with ZITADEL's introspection endpoint, and returns a payload to the frontend. The backend returns the error invalid audience (APP-Zxfako).

You must add the scope urn:zitadel:iam:org:project:id:{projectId}:aud to the auth request that is send from the front end. Replace projectId with the projectId of your backend.

Accessing ZITADEL's APIs

You have a project for a frontend application. The application should also access the API of your ZITADEL, for example to pull a list of all users and display them on a user page. End-users authenticate to the application in the frontend project, but when calling the management API you get the error invalid audience (APP-Zxfako).

You must add the scope urn:zitadel:iam:org:project:id:zitadel:aud to the auth request that is send from the front end.

When accessing your ZITADEL instance's APIs they act as a resource server. You can check the Console or via API and see that when you open your default organization there exists a project "ZITADEL" that contains different applications for each API and the Console. Like in the scenario above the access token requires to have an aud claim that includes the "ZITADEL" project. Instead of urn:zitadel:iam:org:project:id:zitadel:aud you could also use urn:zitadel:iam:org:project:id:{projectId}:aud, where projectId is the projectId of the Project "ZITADEL".

WebFinger requirement for Tailscale

The WebFinger requirement and setup is a step a user has to take outside of their IdP set-up. WebFinger is a protocol which supports the ability for OIDC issuer discovery, and we use it to prove that the user has administrative control over the domain and to retrieve the issuer. This is a requirement we have in place for all users, regardless of their IdP, who use custom OIDC with Tailscale.

On their custom domain, e.g, users need to host a WebFinger endpoint at When queried, this endpoint returns a JSON response detailing the issuer. Users would need to host the endpoint with the link to the ZITADEL issuer. Tailscale only looks up this endpoint once when a user signs up, and will only look up this endpoint again if the user needs to make a configuration change to their identity provider.

The requirements and a set up guide is detailed in the Tailscale documentation.