Use app-specific token signing keys
By default, all applications in a tenant share a single tenant-level key for signing ID tokens and access tokens. This simplifies key management, but some applications may require stricter isolation for security or compliance reasons.
To support these needs, Mosaic allows you to assign app-specific token signing keys. This enables each application to use its own signing key, leveraging standard OIDC and OAuth libraries. It ensures cryptographic isolation at the app level within the same tenant. Enable app-specific signing keys when you need:
- Key isolation between applications
- Separate key lifecycles per app
- Subdomain-based issuer separation in your architecture
Note
- This feature is optional and must be explicitly enabled per app. When enabled, old keys are properly retired and revoked.
- It is fully backward compatible.
Configure app-specific signing keys
To enable app-specific token signing keys, in the app settings (Admin Portal > Applications > select app):
-
Set a
unique subdomain
for the app based on the app and tenant name (e.g.,
acme-corporation.app.transmitsecurity.io
). - Toggle in the Use app-specific token signing keys option.
Once configured, Mosaic provisions a dedicated signing key and manages its lifecycle.
Important
Once enabled, all tokens from the app are signed with its dedicated key—no fallback to the tenant key.
When enabling app-specific token signing:
- Tokens previously signed with the global tenant key remain valid for ~14 days, until they expire naturally.
- Mosaic continues to serve both public keys during this period to support validation.
When disabling app-specific token signing, the admin can choose between:
- Immediately stop honoring tokens signed with the app-specific key.
- Continue honoring those tokens until they expire.
Note
Make sure to include the correct region in your subdomain, depending on your tenant environment:
-
app
— for production in the global/US region, e.g.acme-corporation.app.transmitsecurity.io
-
sbx
— for testing and development (sandbox), e.g.acme-corporation.app.sbx.transmitsecurity.io
-
eu
— for production in the European Union, e.g.acme-corporation.app.eu.transmitsecurity.io
-
ca
— for production in Canada, e.g.acme-corporation.app.ca.transmitsecurity.io
Token structure
Tokens issued by the app include:
-
The app’s subdomain in the
iss
(issuer) claim -
A
kid
(key ID) header referencing the correct key
Token validation libraries resolve the appropriate key automatically based on these fields.
Example ID Token
The following decoded ID token illustrates how app-specific signing is reflected in the token structure:
Header:
{
"alg": "RS256",
"typ": "JWT",
"kid": "appkey-7f439c13"
}
Payload:
{
"iss": "https://acme-corporation.app.transmitsecurity.io",
"sub": "user-12345",
"aud": "client-67890",
"exp": 1723588800,
"iat": 1723585200,
"auth_time": 1723585190,
"email": "user@example.com",
"name": "User Example"
}
Token validation
The relying party must validate the token using the correct public key, available at: https://acme-corporation.app.transmitsecurity.io/oidc/jwks
. Standard JWT validation libraries can automatically select the correct key using the kid
value from the token header.
When validating tokens signed with app-specific keys:
-
Use the
iss
claim to derive the JWKS endpoint (usually${iss}/oidc/jwks
) -
Select the correct public key using the
kid
in the JWT header - Cache the JWKS response and respect its expiration headers to reduce overhead
- Implement fallback behavior for key rotation if your system enforces strict verification
Note
You can also discover the correct JWKS URI dynamically from the jwks_uri
field at:
${iss}/.well-known/openid-configuration
Audit logging
The following events are recorded in admin audit logs:
-
enableAppSpecificSigningKey
: Token signing with an app-specific key was enabled -
disableAppSpecificSigningKey
: Token signing with an app-specific key was disabled