System API JWT token struggles

[reactima]

Preflight Checklist

• I could not find a solution in the existing issues, docs, nor discussions
• I have joined the ZITADEL chat

Describe your problem

If you are struggling with System API JWT token related issues, here are few tips:

It can be result of:

1. misconfiguring zitadel-tool option --audience= --issuer=

https://github.com/zitadel/zitadel-tools

you can double check payload and verify signature with public key here

https://jwt.io/

2. diffrent behavior of openssl and base64 tools on macos and ubuntu

can be caused how/where you generate output of "base64 system-user-1.pub" command

i didnt dig deeper, but can be caused by stupid thing like trying copy-paste keys into your editor and later differences in encoding or \n \r symbols

3. misconfiguring or typo in username

SystemAPIUsers:
  - system-user-1:
      KeyData: <base64 encoded value of system-user-1.pub>

4. expired token

To understand all the above I had to go ... very deep into code

I was able to trace my issues by studying APITokenVerifier, VerifySystemToken functions output ...

zitadel/internal/api/authz/context.go

Line 114 in 3396657

sysMemberships, userID, sysTokenErr = t.VerifySystemToken(ctx, tokenWOBearer, orgID)

VerifyAccessToken
https://github.com/zitadel/oidc/blob/6d1231cb37c27f29ed6fc52bb52d5e7e260ca2dc/pkg/op/verifier_access_token.go#L31

Recommend to re-read documentation
https://github.com/zitadel/zitadel/tree/main/docs/docs/guides/integrate/zitadel-apis

And use grpcui
https://github.com/fullstorydev/grpcui

Zitadel code worked as intended, but I have to admit it was a struggle to understand and debug.

What I was trying to replication with System API is an experience similar to Terraform.

I didnt want to configure test environment by clicking through all UI features. I wanted to get a POC all configuration options are reproducible through the code.

Hope it helps

Describe your ideal solution

The ideal solution is just more error handling messages and more documentations

Version

latest

Environment

Self-hosted

Additional Context

No response