Manage clients

You can manage clients using Application APIs (with an access token of the relevant app or with an admin access token), Client APIs (with an access token of the relevant app), or from the Admin Portal.

SSO Service

This page covers clients managed from Applications > your app > Clients. To set up the SSO Service, create clients from the SSO Service client group page instead. See Configure SSO Service.

Understand client paths

Before creating a client, consider which setup model best fits your use case:

User authentication client: for end-user authentication, supported platform services, and authentication flows based on OIDC, SAML, or backend-based integration patterns tied to your application.
Service client: for API-only backend-to-backend integrations such as Fraud Prevention (DRS), Identity Verification (IDV), and generic machine-to-machine (M2M) use cases. For the complete settings list, see Service client flow.

These are creation-time setup models used to streamline the initial configuration.

Note

Unless stated otherwise, Mosaic documentation refers to OIDC clients simply as clients. For the complete settings list, see OIDC flow.

Manage clients

You can manage clients from Application > Clients tab:

Create a client by clicking + Add client and configuring its settings.
Edit a client by clicking and then Edit.
Delete a client by clicking and then Delete.

OIDC flow

The OIDC flow is available under User authentication client when protocol-based authentication is enabled and OIDC is selected. This section covers both first-party and third-party OIDC clients.

Step 1 - General

Field	Description
Client name	Client name to display when needed.
Client description	Short description of your client.

Step 2 - Authentication flow

Field	Description
Does your login use OIDC or SAML authentication?	Leave this on to continue with protocol-based authentication settings in this step. Turn it off to keep the same User authentication client path but continue with backend-based authentication instead.
Protocol	Setting to OIDC defines that this client is OIDC-based.
Client type	Whether the client is a web app (default) or a native app (e.g., mobile). This is used to adapt validations and configuration according to client type when relevant (such as validations for redirect URIs).
Redirect URIs	List of URIs approved for redirects for your application (e.g., URI to redirect to when an authentication is completed). The required format of the redirect URI depends upon client type: web clients must use HTTPS unless using a local environment, while native apps must use HTTPS unless using a local environment or custom scheme. Custom schemes are only allowed in the format of reverse domain schemes (`[domain]://[scheme]`).
3rd-party client	Available only for OIDC-based clients. Enabling the toggle marks the client as third-party. With the right consent, third-party clients that represent external services can request access to your protected resources on behalf of the user. It includes: Consent redirect URL: List of URIs for obtaining user consent (e.g., URI to redirect to when a third-party client requests access to user data). These pages should be managed by the first-party client. Consent validity period: Currently, set to 30 days. Scopes: List of resources the third-party client is allowed to access on behalf of the user in the app. Third-party clients typically have limited control over user data.

Step 3 - Advanced settings

Field	Description
Enforce FAPI 2.0 compliance	For highly-regulated industries, consider enabling "Enforce FAPI 2.0 compliance". This will automatically disable client settings that aren't FAPI 2.0-compliant and prompt you to configure your client in accordance with FAPI principles, for example by enforcing mTLS, PKCE, and PAR. See FAPI 2.0.
Authentication method	Enforces client authentication using a specific method: Client Secret: (default) Allows authenticating using Client ID and Client Secret. For security purposes, the secret can be rotated later without changing the client ID. Private key JWT: Allows authenticating using client JWT assertion signed by your private key. If selected, provide JWKS. mTLS (self-signed): Allows leveraging an mTLS handshake for authentication. If selected, provide the self-signed certificate in the JWKS format. mTLS (CA-signed): Allows leveraging an mTLS handshake for authentication. If selected, provide the certificate chain in the PEM format. For requirements, see Authenticate using mutual TLS. Optionally, define Subject DN attributes (Common name (`CN`), Organization (`O`), and others) to enforce certificate validation against these values.
Enable token binding	Enabling this ensures that tokens are cryptographically bound to client certificate in the mTLS and private key JWT flows.
Enforce PAR	Enforces the usage of the PAR endpoint for auth requests. For implementation details, see Integrate login using PAR.
PKCE support	Whether the client requires the proof key of code exchange (PKCE) for authentication. For implementation details, see Secure login with PKCE. Allow PKCE alongside client credentials: (default) Allows auth requests with and without PKCE, provided that they use client credentials. Enforce PKCE alongside client credentials: Requires all authentication requests to include PKCE in addition to client credentials. Enforce PKCE instead of client credentials: Retrieves user access tokens only. For security reasons, Mosaic doesn't recommend using PKCE as a standalone method for authenticating users without the Client Secret.
Access token expiration	The access token time-to-live. By default, 60 minutes.
Refresh token expiration	The refresh token time-to-live. By default, 2 weeks.
Max refresh time	The maximum period of time when the refresh token can be rotated. By default, 2 weeks.
Session expiration	The validity period during which you can silently authenticate the session. By default, 2 weeks, and can be configured up to 1 year.
Same Site	Defines the client cookie policy for requests made from a different site (cross-site). LAX: Allows Mosaic session cookies to be sent during standard navigation flows while blocking most cross-site requests (iframes and POSTs). This provides strong CSRF protection with minimal impact on typical sign-in experiences. None: Allows sharing Mosaic session cookies. This option can only be used for HTTPS redirect URIs.
Supported prompt values	List of OIDC prompt values to be enforced by the OIDC authorization server. Note that only selected prompt values can be included in the authorization requests, requests containing unselected prompt values will be rejected. Login: Forces the user to authenticate. Consent: Obtains user's consent. Required to obtain a refresh token. None: Checks for an existing session.
Resources	List of URIs the client can explicitly request access to. This allows the client to manage dedicated access for a resource, including the token expiration. For example, a website can have a shorter lifetime for the page used to manage the user's payment methods. Before a resource can be added to a client, it must first be created from the Resources tab of the Applications page (see Resources).
ID token — Pre-defined custom claims	Dropdown for selecting the claim values that Mosaic should return by default in the user's ID token. These claims do not need to be explicitly requested in the OIDC authorization request. Pre-defined ID token custom claim list is available below this table.
Return ID token claims on UserInfo as well	Checkbox that makes the UserInfo endpoint return the same default claims selected in ID Token - Pre-defined Custom Claims. When selected, User info - Pre-defined Custom Claims is disabled because UserInfo uses the ID token claim selection.
User info — Pre-defined custom claims	Dropdown for selecting the claim values that Mosaic should return by default from the UserInfo endpoint. These claims do not need to be explicitly requested during the OIDC flow. Pre-defined UserInfo custom claim list is available below this table.
ID token encryption	Allows encrypting ID tokens using the customer-provided key. Upload a JWKS containing an RSA public key (RSA-OAEP) and rotate it as necessary. Encrypted tokens will be returned in a JWE form.

ID Token - Pre-defined Custom claims list

Click to open the list

tid: ID of the Mosaic tenant
fname: User's first name
lname: User's last name
mname: User's middle name
email: User's primary email
email_verified: Indicates if the user's primary email is verified
phone_number: User's primary phone number
phone_number_verified: Indicates if the user's primary phone number is verified
groups: Groups to which the user belongs
new_user: Indicates if a new user was created as part of the authentication flow
birthday: User's birthday as YYYY-MM-DD
language: The language of the user
city: User's city of residence
address: User's address
country: User's country of residence
street_address: User's street address
address_type: Type of user's address
webauthn: Returned only if WebAuthn was used
roles: List of role IDs assigned to the user
ts_roles: Transmit Security platform roles assigned to the user through Transmit Security RBAC. These are distinct from the application-level roles in the roles claim
role_values: Main and custom roles assigned to the user
ts_permissions: Transmit Security platform permissions assigned to the user through Transmit Security RBAC. These are distinct from the application-level permissions in the permissions claim
permissions: List of permissions delegated to the user
approval_data: Returned only in transaction signing flows. Contains approval-related transaction data
custom_group_data: Custom data object for group info
username: Username used to identify the user for password login
secondary_phone_numbers: List of user's secondary phone numbers
secondary_emails: List of user's secondary emails
picture: The picture of user, specified as a URL
created_at: Date user was created in the tenant
last_auth: Date user last authenticated
auth_time: Time the user was authenticated
external_account_id: User identifier in an app, set by the app
external_user_id: A unique identifier in a tenant
app_name: Name of the app the user is associated with
custom_data: Custom data object for tenant user info
custom_app_data: Custom data object for app-related user info

User info - Pre-defined Custom claims list

Click here to open the list

tid: ID of the Mosaic tenant
fname: User's first name
lname: User's last name
mname: User's middle name
email: User's primary email
email_verified: Indicates if the user's primary email is verified
phone_number: User's primary phone number
phone_number_verified: Indicates if the user's primary phone number is verified
groups: Groups to which the user belongs
new_user: Indicates if a new user was created as part of the authentication flow
birthday: User's birthday as YYYY-MM-DD
language: The language of the user
city: User's city of residence
address: User's address
country: User's country of residence
street_address: User's street address
address_type: Type of user's address
webauthn: Returned only if WebAuthn was used
roles: List of role IDs assigned to the user
ts_roles: Transmit Security platform roles assigned to the user through Transmit Security RBAC. These are distinct from the application-level roles in the roles claim
role_values: Main and custom roles assigned to the user
ts_permissions: Transmit Security platform permissions assigned to the user through Transmit Security RBAC. These are distinct from the application-level permissions in the permissions claim
permissions: List of permissions delegated to the user
approval_data: Returned only in transaction signing flows. Contains approval-related transaction data
custom_group_data: Custom data object for group info
username: Username used to identify the user for password login
secondary_phone_numbers: List of user's secondary phone numbers
secondary_emails: List of user's secondary emails
picture: The picture of user, specified as a URL
created_at: Date user was created in the tenant
last_auth: Date user last authenticated
auth_time: Time the user was authenticated
external_account_id: User identifier in an app, set by the app
external_user_id: A unique identifier in a tenant
app_name: Name of the app the user is associated with
custom_data: Custom data object for tenant user info
custom_app_data: Custom data object for app-related user info

Customizing claims

Claims such as org_id do not appear in these dropdowns. When authentication runs in the context of an organization, Mosaic adds org_id automatically to the ID token and UserInfo response.

To add custom key/value claims in journey flows, configure Enrich Access and ID Token or Enrich SSO Token in your journey.

Important

Upon OIDC client creation, Mosaic will autogenerate a unique Client ID and Client Secret.

Client ID: Client identifier for API requests, automatically generated when the client is created. It cannot be edited.
Client Secret: Client secret used to authorize API requests on behalf of the client (either directly or by using it to generate client access tokens). It is automatically generated when the client is created, and you can rotate it later without changing the Client ID. During rotation, Mosaic can keep up to two active secrets so you can update your backend before revoking the old one.

Step 4 - Client roles

The last step lets you assign one or more client roles to the client. Setting roles isn't available to third-party OIDC clients.

Field	Description
Client roles	Assign one or more client roles to the client.
Client roles > Add a new role	Opens the Add role flow: Step 1 - Details: enter the required Role name and optional Description. Step 2 - Setup: assign permissions from the permission tree under Mosaic capability areas, Identity management, Authentication, Platform Administration, and Fraud Prevention, each expanding into more granular categories. For more details, see Manage client roles.

SAML flow

The SAML flow is available under User authentication client when you choose SAML as the protocol.

Step 1 - General

Field	Description
Client name	Client name to display when needed.
Client description	Short description of your client.

Step 2 - Authentication flow

When you select SAML as the protocol, this step shows the SAML settings section.

Field	Description
Does your login use OIDC or SAML authentication?	Leave this on to continue with protocol-based authentication settings in this step. Turn it off to keep the same User authentication client path but continue with backend-based authentication instead.
Protocol	Setting to SAML defines that this client is SAML-based.
Service provider (SP) ACS URL	The endpoint where SAML responses containing authentication assertions are sent after the user successfully logs in. This URL must be configured accurately to ensure that the authentication data is received and processed by the intended application.
Service provider (SP) Entity ID	ID that uniquely identifies the service provider within the SAML framework. This is crucial for ensuring that the SAML responses are directed to the correct client application, maintaining the integrity and security of the authentication process.

Important

Upon SAML client creation, Mosaic will autogenerate a unique SAML SSO URL, Transmit Entity ID, X.509 Certificate and IDP metadata URL.

SAML SSO URL: The URL acts as the gateway for routing login requests through the correct SSO mechanism. This URL must be set within the relying party (RP).
Transmit Entity ID: ID that uniquely identifies the Mosaic IDP in the SAML exchange, ensuring that SAML requests are routed to the Mosaic.
X.509 Certificate: The certificate used to sign SAML assertions, securing communication between the application and the identity provider.
IDP metadata URL: The Mosaic endpoint that contains structured metadata about the IDP's configuration.

Step 3 - Additional information

Field	Description
NameID	Choose the user identifier sent in the SAML assertion. The default value is Email. Options include Email, Secondary Email, Username, Phone Number, and External User ID.
Sign SAML assertion	If enabled, in addition to the signing of the entire SAML response Mosaic signs the SAML assertion with the generated X.509 certificate.
Allow the ACS URL to be optional in SAML requests	If enabled, the SAML AuthnRequest can omit the `AssertionConsumerServiceURL`, and Mosaic uses the ACS URL configured on the client instead. Checking this option may reduce security by disabling ACS URL validation.
Same Site > LAX	Allows Mosaic session cookies to be sent during standard navigation flows while blocking most cross-site requests, such as iframes and POSTs. This works for most apps and provides strong CSRF protection with minimal impact on typical sign-in experiences.
Same Site > None	Allows sharing Mosaic session cookies in cross-site or iframe scenarios. Requires HTTPS (Secure cookies) and can only be used for HTTPS redirect URIs.

Service client flow

The Service client path is a three-step flow after the initial client-type selection. Use this path for:

Fraud Prevention clients that call risk-evaluation APIs and SDKs
Identity Verification clients that call APIs and SDKs
Backend clients for generic server-to-server integrations

Step 1 - General

Field	Description
Client name	Client name to display when needed.
Client description	Short description of your client.

Step 2 - Advanced settings

Field	Description
Authentication method	Enforces client authentication using a specific method: Client Secret: (default) Allows authenticating using Client ID and Client Secret. For security purposes, the secret can be rotated later without changing the client ID. Private key JWT: Allows authenticating using client JWT assertion signed by your private key. If selected, provide JWKS. mTLS (self-signed): Allows leveraging an mTLS handshake for authentication. If selected, provide the self-signed certificate in the JWKS format. mTLS (CA-signed): Allows leveraging an mTLS handshake for authentication. If selected, provide the certificate chain in the PEM format. For requirements, see Authenticate using mutual TLS. Optionally, define Subject DN attributes (Common name (`CN`), Organization (`O`), and others) to enforce certificate validation against these values.
Enable token binding	Enabling this ensures that tokens are cryptographically bound to client certificate in the mTLS and private key JWT flows.
Token timeout configuration	Allows modifying default token expiration times: Access token expiration: The access token time-to-live. By default, 60 minutes. Refresh token expiration: The refresh token time-to-live. By default, 2 weeks. Max refresh time: The maximum period of time when the refresh token can be rotated. By default, 2 weeks. Session expiration: The validity period during which you can silently authenticate the session. By default, 2 weeks, and can be configured up to 1 year.
Additional settings	Expand this accordion to configure optional service-client settings exposed by your tenant.
Resources	List of URIs the client can explicitly request access to. This allows the client to manage dedicated access for a resource, including the token expiration. For example, a website can have a shorter lifetime for the page used to manage the user's payment methods. Before a resource can be added to a client, it must first be created from the Resources tab of the Applications page (see Resources).

Step 3 - Client roles

This last step lets you assign access to the service client by selecting an existing client role or creating one inline.

Field	Description
Client roles	Assign one or more client roles to the client.
Client roles > Add a new role	Opens the Add role flow: Step 1 - Details: enter the required Role name and optional Description. Step 2 - Setup: assign permissions from the permission tree under Mosaic capability areas, such as Identity management, Authentication, Fraud Prevention and more. For more details, see Manage client roles.

Service clients don't require redirect URIs, SAML federation, supported prompt values, PKCE, or OIDC token-claim configuration.