Authorization header:
Setup
Set the public key URL in the admin panel or in the environment.- Admin panel
- Environment
Go to Admin Panel → Organization → Security & Hardening. In the External JWT Authentication section, set:
- Public Key URL: the JWKS or PEM endpoint that serves your signing key. Leave it empty to turn JWT authentication off.
- Expected Audience (optional): reject tokens whose
audclaim does not match. - Expected Issuer (optional): reject tokens whose
issclaim does not match.
- JWKS: a JSON document with a
keysarray. Onyx picks the key whosekidmatches the token header, then falls back tox5t. If the set has one key, Onyx uses it. - PEM: a single RSA public key in PEM format.
Token Requirements
- Signing algorithm:
RS256. expmust be present and in the future.- One of these claims must hold the user’s email. Onyx checks them in this order:
email,preferred_username,upn. audandissare checked only when you set Expected Audience or Expected Issuer.
User Handling
- If the email matches an existing user, the request runs as that user.
- If no user matches, Onyx creates a basic user with that email. The user has no password and signs in with a token only.
- The request does not create a session. Each request must carry a token.
- A valid session cookie takes priority over the header. Onyx reads the
Authorizationheader only when there is no session.
Troubleshooting
A request with a bad token fails as unauthenticated. Check the API server log for the reason:
For admin-set URLs, Onyx blocks private and internal addresses by default.
See SSRF Protection in Security & Hardening, or set the URL with
JWT_PUBLIC_KEY_URL instead.
Related
- API Keys: long-lived keys for service accounts.
- SSO Providers: browser sign-in with Google, OIDC, or SAML.