When users authenticate or clients obtain access in Mosaic, ID tokens, user access tokens, and client access tokens are issued and cryptographically signed with dedicated token signing keys to protect their integrity (Journey tokens are excluded).
Mosaic supports multiple token signing strategies. Each strategy differs in key ownership, isolation level, and compliance suitability. Choose the one that best fits your architecture and security requirements.
All strategies are compatible with standard OAuth 2.0 and OpenID Connect token validation libraries. For details on how to validate tokens, see this guide.
By default, Mosaic uses a single Global signing key to sign tokens for all applications within a tenant. It is a tenant-level key, automatically provided at tenant creation and fully managed by Mosaic, and is used to sign all tokens issued by applications in the tenant (Journey tokens are excluded).
As a consequence, the Global signing key requires no setup and no key management on your side, and Mosaic is responsible for key generation, storage, and lifecycle management.
Keep using the Global signing key when:
- you want zero key management overhead,
- you do not require cryptographic isolation between applications within your tenant,
- you want a single, consistent signing authority across all apps,
- you need FAPI-compliant deployments that require PS256,
- you do not want to manage private keys yourself.
In some scenarios, a tenant-wide signing key is not enough. Some use cases require stronger isolation between applications for security or compliance reasons.
App-specific signing keys enable each application to use its own signing key, leveraging standard OIDC and OAuth libraries. This 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
App-specific signing keys can be configured in two ways:
- System-generated keys — Mosaic generates and manages the key for you
- Bring Your Own Key (BYOK) — You provide and control the signing key material
Mosaic doesn't rotate app-specific signing keys automatically. You control rotation in the Admin Portal to keep token validation uninterrupted. FInd more in the Key statuses and rotation section below.
Both system-generated keys and BYOK currently support RS256 only. If you require PS256 (for example, for FAPI compliance), use the Global signing key instead.
Mosaic can generate a dedicated signing key for your application. This provides app-level isolation while still allowing Mosaic to manage the key lifecycle.
You may choose system-generated app-specific keys when you need cryptographic isolation between applications or independent rotation per app, but do not want to generate, store, or manage key material yourself.
The Bring Your Own Key (BYOK) capability lets you replace the Mosaic-generated signing key with a private key that is fully generated, owned, and controlled by your organization.
By using BYOK, token signing operations rely on cryptographic material that never leaves your control, ensuring full ownership and custody of the private key and its certificate.
You may choose to use BYOK when you need:
- Regulatory compliance that requires the private key to be generated and stored by the customer.
- Key isolation, ensuring the signing key is not shared across applications or tenants.
- Full lifecycle control, including key generation, rotation, and revocation.
- Operational transparency, with explicit control over which key signs tokens at any given time.
To use BYOK, the signing key you upload must meet the following requirements:
- RSA 2048-bit key.
- Supported algorithm: RS256.
- The key must comply with OIDC and OAuth standards.
- The key material must be valid, uncorrupted, and not expired.
- The key and its associated certificate (if provided) must be consistent with each other.
When using BYOK, you are responsible for the cryptographic material itself, including key validity, rotation timing, and certificate expiration.
Failure to manage the key correctly may result in token validation failures and service disruption.
Use this procedure to configure an app-specific signing key for an application, regardless of whether the key is generated by Mosaic or provided by you (BYOK).
Both options follow the same lifecycle and rotation model once the key is added.
In the Admin Portal, go to Applications and select the relevant app.
Set a unique domain for the app before configuring signing keys. The domain can be either a subdomain (for example,
acme-corporation.app.transmitsecurity.io) or a custom domain that you own. If the app already has a unique domain configured, reuse it to proceed to the Signing keys section—there’s no need to create a new one. Then click Add to save the app.NoteIf using a subdomain, make sure to include the correct region in your domain, depending on your tenant environment:
app— production (US), for exampleacme-corporation.app.transmitsecurity.ioca— production (Canada), for exampleacme-corporation.app.ca.transmitsecurity.ioau— production (Australia), for exampleacme-corporation.app.au.transmitsecurity.ioeu— production (EU), for exampleacme-corporation.app.eu.transmitsecurity.iosbx— sandbox/testing, for exampleacme-corporation.app.sbx.transmitsecurity.io
After saving, the Signing keys section appears, displaying the Global signing key already running at the tenant level.
To add an app-specific signing key, click Add key and choose one of the following options:
Option A: Add a system-generated key
Click Add key > Add system-generated key. Mosaic creates a dedicated signing key for the app in Disabled status.Option B: Upload your own key (BYOK)
Click Add key > Upload your own key, then provide a friendly name and upload the key material. The uploaded key is added in Disabled status.
To ensure token continuity, set the Global key (or the current Signing key) to Validating. From the key's actions menu, select Set as validating.
To start using your key for new tokens, from the custom key's actions menu promote the app-specific signing key you created to Signing. All newly issued tokens for the app are now signed with this key.
Each application can store up to four keys. Each key has one of the following statuses:
- Signing — Signs all newly issued tokens. Only one key can be Signing at a time.
- Validating — Published in the JWKS to validate previously issued tokens until they expire.
- Disabled — Excluded from the JWKS and no longer valid for token validation.
Once a key is set to Signing, it is immediately used to sign all newly issued tokens. Only keys in Signing or Validating status are published in the JWKS and can validate tokens. Keys in Disabled are immediately excluded from validation.
To rotate keys safely and maintain token continuity, follow this sequence:
Upload or create a new signing key to your application (either system-generated or BYOK).
Set the new key to Validating status.
This publishes it in the JWKS, allowing your backend systems and relying parties to retrieve the new public key and prepare for the key switch before it becomes active. The old key remains in Signing status during this preparation period.Continue accepting tokens signed with the old key. During this transition period, tokens signed with the old key (still in Signing status) continue to be accepted and validated. This gives time for the new key to propagate to all systems that need it.
Start signing new tokens with the new key. Once the new key has had time to propagate (typically close to the time of the actual key switch), set the new key to Signing status and move the previous Signing key to Validating. All newly issued tokens will now be signed with the new key, while previously issued tokens continue to validate with the old key.
Remove the old key after sufficient time. After a sufficient period (typically the maximum token lifetime plus a grace period), set the old key to Disabled. This removes it from the JWKS. Ensure no active tokens depend on the old key before disabling it.
You can rotate keys or switch signing key strategy at any time (Global signing key, App-specific signing keys, or BYOK). Token continuity depends entirely on the key statuses you set—Mosaic does not apply any automatic fallback or grace period.
The Global signing key can also be used as a transition key when rotating or switching to other strategies (app-specific or BYOK), by keeping it in a Validating state while another key becomes active.
After configuring your token signing keys, learn how to validate tokens to protect your APIs and ensure tokens are properly verified before granting access to resources.