Backend API journeys

Backend API journeys enable service-to-service communication by exposing Mosaic Identity Orchestration workflows as RESTful API endpoints. These journeys allow backend systems, such as Interactive Voice Response (IVR) tools, fraud detection systems, or CRM platforms, to interact with Mosaic through HTTP requests. This capability makes it possible to integrate identity workflows seamlessly into automated backend processes you own.

Backend API journeys are designed to process complex logic without requiring any client-side interaction. Operating entirely on the server side, they do not support steps that collect information from the client. This makes them ideal for scenarios where backend systems need to perform identity-related tasks autonomously, such as verifying user details, processing risk signals, or triggering external workflows (for more, see the use case examples below).

Key features

  • Service-to-service communication: These journeys act as RESTful API endpoints, accepting HTTP GET or POST requests and responding with HTTP status codes and payloads. This allows backend systems to invoke journeys programmatically, integrating Identity Orchestration into the automation processes.
  • Customizable workflows and scalable design: Backend API journeys can be tailored to specific use cases, from simple one-step processes to more complex workflows involving multiple backend interactions. Backend API journeys support:
    • External connections to interact with third-party services or retrieve additional data. For example, query a customer data platform (CDP) to retrieve user preferences and dynamically tailor the experience within the journey.
    • Control structures , such as:
      • Condition: Branch logic based on external API results. For instance, route the user to a success or failure step depending on the payment validation response.
      • Match Case: Configure multiple outcomes for diverse scenarios. For instance, customize the response based on CRM data, such as offering different onboarding flows for new or returning users.
  • Security and token validation: These journeys rely on access control and client access token validation, ensuring secure communication and protecting against malicious requests. For more, see the data security and token validation section below.
  • Error handling and response management: Backend API journeys support configurable response codes to manage errors. To do so, the HTTP Complete Journey step allows you to set specific Response Codes (e.g. 2xx , 3xx , 4xx or 5xx ) that you can use to direct the flow to specific branches, or to notify calling services of the outcome. For more about HTTP responses, see the Output section below.

Use cases

Backend API journeys facilitate service-to-service workflows by enabling seamless communication between Mosaic and external systems. Here are some examples:

  • Customer interaction automation: Integrate Mosaic with tools like IVR systems or CRM platforms to verify user identities, trigger backend-driven decisions, and deliver personalized workflows.
  • Operational data management: Synchronize user profiles, allocate resources, or manage dynamic updates between Mosaic and external systems for streamlined backend operations.
  • Transaction handling: Validate transaction details or conduct pre-authorization checks by connecting Mosaic with payment or financial systems.

Data security and token validation

Mosaic APIs are authorized using Bearer access tokens in the header of the request.

Backend API journeys are authorized using Bearer access tokens in the header of the request. This involves validating the client access token, ensuring that only authorized services can invoke the journey.

Client access token validation is enabled by default in the journey creation screen. When enabled, every API call initiating a journey must include a valid Mosaic client access token in the Authorization header (Authorization: Bearer <token>). Upon receiving the API request, Mosaic's platform validates the token before executing the journey by performing the following checks:

  • Parameter integrity enforcement: Ensures the clientId parameter in the API request matches the sub claim within the token.
  • Access Control: Rejects the request with a 401 Unauthorized response if the token is invalid or expired.

For detailed instructions on generating and validating Mosaic client tokens, see our Get client access tokens guide.

Backend API journey output

The output of a backend API journey allows you to send a structured HTTP response back to the calling application or service. This response can trigger further actions or workflows based on the returned HTTP status code and payload.

Backend API journeys support a wide range of RESTful response codes, which can be categorized as follows:

  • Success (2xx): Indicate that the request was successfully processed. Examples include confirming an operation ( 200 OK ) or signaling resource creation ( 201 Created ).
  • Redirection (3xx): Direct the calling service to an alternate endpoint. Common scenarios include temporary or permanent redirects ( 302 Found , 307 Temporary Redirect ).
  • Client Errors (4xx): Notify the caller of issues with the request, such as invalid inputs ( 400 Bad Request ), lack of authorization ( 401 Unauthorized ), or forbidden access ( 403 Forbidden ).
  • Server Errors (5xx): Indicate problems on the server side, such as an unexpected failure ( 500 Internal Server Error ) or unsupported functionality ( 501 Not Implemented ).

The flexibility of these response codes allows backend API journeys to seamlessly integrate with various automation workflows, making them adaptable to a wide range of use cases.

For more on how to configure the HTTP response, see the HTTP Complete Journey Step.

Next steps

For a hands-on example of building backend API journeys, see the backend API journey tutorial.