The Well Known screen manages the public configuration that Versola serves to the outside: the JSON Web Key Set (JWKS) that lets clients and APIs verify your tokens, and the server metadata document. You use it to generate a signing key, publish a key you hold elsewhere, or retire an old one. A key only signs tokens for a tenant after you select it under Token Signing Key on Challenges & Security.
Before you start
| Need | Permission |
|---|---|
| See the keys and the metadata | jwks:read |
| Generate, add, edit or delete keys, edit the metadata | jwks:manage |
The screen is global, not scoped to the tenant selector. Without jwks:manage the + Add Key, Generate Key, ✎ and ✕ controls are not shown.
JWKS
Each key is a card with its kid, its type and algorithm (for example EC · ES256), a badge and the JWK as published. The badge tells you what Versola can do with the key:
| Badge | Meaning |
|---|---|
| Can sign | Central holds the private half and the key has a known alg. A tenant can select it as its Token Signing Key. |
| Verify only | Central holds only the public JWK. The key is published so verifiers accept it, but nothing signs with it. |
A deployment that is seeded from bootstrap.jwks starts with verify-only keys, because Central never receives their private halves. Generate a key to get one that can sign.
Algorithms
The selector next to Generate Key offers three algorithms:
| Algorithm | Key generated | Notes |
|---|---|---|
PS256 | RSA-2048 | The default choice when a new tenant has no key selected. |
ES256 | EC, curve P-256 | Also acceptable under FAPI 2.0. |
RS256 | RSA-2048 | Can be generated on any tenant but selected for signing only on a tenant with the Standard security profile. Central refuses it on a FAPI 2.0 tenant. |
PS256 and ES256 are both allowed on either profile. HS256 is not offered: a shared secret has nothing to publish in a JWKS. The kid of a generated key is a timestamp plus the algorithm, for example 2026-10-14_07-29-17-es256.
Generate Key
Generate Key creates a key pair for the selected algorithm, publishes the public half at once and stores the private half in Central, encrypted at rest. The private key is not shown and cannot be downloaded.
The note under the buttons states the consequence: a generated key is published for verification immediately but signs nothing until a tenant selects it under Challenges & Security, so every verifier learns the key before anything issues tokens under it.
+ Add Key
+ Add Key opens Add JWK, a JWK JSON field where you paste a public JWK. Use it to publish a key whose private half you keep elsewhere. The console requires kid and kty; Central requires a kid and answers JWK must contain a 'kid' field or Invalid JWK JSON otherwise. A key added this way is always Verify only.
Edit and delete
The ✎ icon opens the JWK of an existing key for editing; the kid cannot be changed (delete the key and add a new one instead). The ✕ icon asks for confirmation in a Delete JWK dialog and then removes the key from the JWKS.
Central refuses to delete a key that a tenant still signs with, with Key '<kid>' is the signing key of <tenants>. Select another key for them before deleting it. Move those tenants to another key first. Once a key is deleted, it is no longer published, so nothing can verify tokens that were signed with it.
Where the keys are used
| Consumer | Uses |
|---|---|
auth, signing | For each tenant, the key selected as Token Signing Key signs access tokens, ID tokens and logout tokens. The algorithm comes from the key. A tenant with no selection signs with the private key in the jwt.private-key configuration of auth. |
auth, publishing | GET /.well-known/jwks.json returns the public halves of all keys, with Cache-Control: public, max-age=86400. It needs no authentication. Resource servers should refetch on an unknown kid instead of waiting for the cache to expire. |
edge | Verifies tokens with the public halves it syncs from Central. It never receives a private key. |
| Central | Verifies the tokens of the admin console with the same keys. |
The format of the set is RFC 7517. The Central endpoints behind this screen (/configuration/jwks) are described in the OpenAPI reference.
Rotating a signing key
The screen supports a rotation in three steps:
- Generate Key for the algorithm you want. The new key is published and nobody signs with it yet.
- Open Challenges & Security for each tenant and select the new key under Token Signing Key.
authswitches to it after it has synced the key; until then it keeps signing with the previous key. - Delete the old key when no token you still need to verify is signed with it. Wait at least as long as the longest-lived token signed with it and as long as verifiers cache the JWKS (24 hours for responses of
auth).
Versola does not rotate keys on a schedule and does not retire them for you.
Server Metadata
Below the keys, Server Metadata shows the authorization server metadata document as JSON. ✎ opens it for editing. The console requires issuer, authorization_endpoint, token_endpoint, jwks_uri and response_types_supported and refuses to save without them. auth serves the document at /.well-known/openid-configuration and /.well-known/oauth-authorization-server. The authorization_details_types_supported member is kept in step with the types you register on Challenges & Security. See RFC 8414.
Next steps
- Challenges & Security to select the signing key per tenant
- Security profiles for the RS256 rule
- RFC 7517 and the OpenAPI reference