Skip to content

Configure service clients

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
  • Machine-to-machine (M2M) clients for server-to-server integrations, such as a backend that calls Mosaic identity management or authentication APIs
  • Platform Administration clients that call Mosaic management APIs within their Mosaic application, for example to manage the Mosaic application and its clients

A service client operates within the scope of its Mosaic application. For administrative operations across Mosaic applications, use management apps.

Before you start

Create a Mosaic application for the client and identify the API permissions your integration needs.

In Applications > your app > Clients, click + Add client and select Service client. Complete the three steps below.

Step 1 - General

FieldDescription
Client nameClient name to display when needed.
Client descriptionShort description of your client.

Step 2 - Advanced settings

FieldDescription
Authentication methodEnforces 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 bindingEnabling this ensures that tokens are cryptographically bound to client certificate in the mTLS and private key JWT flows.
Token timeout configurationAllows 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, 8760 hours (1 year).
Additional settings > ResourcesList of resources the client can explicitly request access to. This allows the client to manage dedicated access for a resource, including the token expiration. Before a resource can be added to a client, it must first be created from the Resources tab of the Applications page (see Resources).
Token exchangeLets clients exchange user access tokens using OAuth 2.0 Token Exchange (RFC 8693). Both options are disabled by default.
  • Initiate token exchange: Allows this client to call /oidc/token with the token exchange grant, as the exchanging client.
  • Delegate tokens issued by this client: Controls which clients may exchange user access tokens issued to this client, as the source client. When enabled, choose All clients within the Application (every client in the same Mosaic application, including dynamically registered clients) or Specific clients / DCR Authorities (manually registered clients you select, and optionally Client authorities, so that clients registered through them can exchange tokens).


See Token exchange.

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. Based on the scope of your backend integration, select:

  • The CIAM role if your backend manages users, sessions, or credentials through identity management APIs, for example to sync users or revoke sessions.
  • The Authentication Only role if your backend only orchestrates authentication flows, for example to run login methods or exchange journey codes.
  • A custom role if your backend needs a specific set of permissions.

For details on the built-in roles, see Built-in roles.

If the service client is used only for Fraud Prevention or Identity Verification, you don't need to assign a client role. If the same backend also interacts with identity management, for example to read or update users, manage sessions, revoke credentials, or run authentication, assign the CIAM role. If it only orchestrates authentication flows, assign the Authentication Only role instead. Fraud Prevention and Identity Verification calls keep working with either role.

FieldDescription
Client rolesAssign one or more client roles to the client, including the built-in roles CIAM role and Authentication Only role. If you don't select a role, the client implicitly receives the App Admin role.
Client roles > + Add roleOpens 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 the Mosaic capability areas Identity management, Authentication, Platform Administration, and Fraud Prevention, each expanding into more granular categories.
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.

After saving

Complete the wizard and save the client. Use its client ID and the configured authentication method to authorize your integration. See Retrieve client tokens.