# Custom validation

Custom validation services allow you to configure a connection to a custom token validation service. Custom validation services rely on a standard HTTP request to an endpoint you define, which validates a token and returns the result. This configuration is particularly useful when you need to validate tokens issued by your own or a third-party authentication service.

Mosaic's Journeys use custom validation services in the [Validate Token](/guides/orchestration/journeys/validate_token) and [Custom Authentication](/guides/orchestration/journeys/authenticate_custom) steps. This enables you to validate tokens provided by the application against your own validation endpoint, supporting scenarios like custom session validation, third-party token verification, or legacy IdP integration.

## How it works

Configuring a custom validation service involves the following steps:

1. **Establishing the connection**: Set up the connection to the validation service by configuring key parameters, including the Request URI, HTTP Request Method, request headers, authentication, and security settings like SSL identities (Admin Portal > Management > Integration hub > Custom Validation).
2. **Defining the request**: Build the request body and headers sent to the validation service. The following parameters are available to be used in expressions:
  - `user_id`: Identifier of the user doing the authentication
  - `token`: The token to be validated as provided by the application
3. **Classifying the response**: Define how the service response is interpreted by configuring the response format, response classifiers that resolve to Valid, Invalid, or Error, and optional custom branches.


At runtime, validating a token consists of:

1. **Sending the validation request**: When the validation executes, it uses the preconfigured connection to send the token and user identifier to the validation service.
2. **Response and handling**: The service response is evaluated against the response classifiers to determine whether the token is valid, invalid, or resulted in an error. Custom branches can route the journey based on additional conditions.


## Configuration

| Parameter | Description |
|  --- | --- |
| Name | A unique name for the custom validation connection. The name may not contain whitespace characters. |
| Category | Preset to Token Validation (read-only). |
| Type | Preset to Custom Token Validation (read-only). |
| **REQUEST: FORMAT** |  |
| Request URI | The endpoint of the custom validation service (e.g., `https://api.example.com/token/validate`). Supports expressions. |
| HTTP Request Method | The HTTP method used for the request: POST, PATCH, PUT, GET, or DELETE. |
| Request Body | Expression that defines the payload sent to the validation service (displayed for methods that support a body, e.g., POST). Can reference the `user_id` and `token` parameters, for example: `{ token: token, user_id: user_id }`. |
| HTTP Request Headers | Name-value pairs added to the request (e.g., `Content-Type`: `'application/json'`). Header values support expressions. |
| **AUTHENTICATION** |  |
| Authentication Type | The authentication scheme used with the validation service: None, Basic, Bearer, OAuth 2 Client Credentials Grant, OAuth 2 JWT Bearer, OAuth 2 Password Grant, AWS Signature v4, or NTLM. |
| Credentials alias | Select a previously defined credential alias or add new ones (displayed for authentication types that require credentials). These credentials represent the secret used with the validation service. For more details, see [Keys & Credentials](/guides/orchestration/keys-and-credentials/overview/#credentials). |
| **SSL IDENTITIES** |  |
| Client Certificate Local Identity | The client certificate (key) presented to the validation service for mutual TLS. Select an existing key or add a new one. |
| Trusted Identities | The server certificates trusted when connecting to the validation service. Select an existing certificate or add a new one. |
| **HTTP CONNECTION SETTINGS** |  |
| Follow Redirect | Follows HTTP redirects returned by the validation service. |
| Request Timeout | The maximum time to wait for the request to complete. |
| Connection Timeout | The maximum time to wait for the connection to be established. |
| **LOGGING** |  |
| Report External Connection Data | Enables additional event reporting for the connector. |
| Data Reported | Determines whether the connector records External Connect Request/Response or Custom. |
| Custom Data Reported | Expression that defines the custom payload recorded for the connector (displayed when Data Reported is set to Custom). For syntax details and examples, see [Additional data reporting](/guides/orchestration/getting-started/event_reporting#report-external-connectors-data). |
| **RESPONSE** |  |
| Return failure if response is invalid | Treats an invalid response from the validation service as a failure. |
| Response Format | The format of the response returned by the validation service: None, String, JSON Array, JSON Object, or XML. |
| Specify JSON schema for response | Validates the response against a JSON schema you provide (displayed for JSON formats). |
| Apply transformation on response received from the web service | Applies a transform expression to the response before it is evaluated. When enabled, define the Transform expression and optionally specify a schema for the transformation result. |
| Response Classifiers | Conditions that classify the response. Each classifier consists of a Condition expression (e.g., `response.active == true`) and a Value: Valid, Invalid, or Error. |
| Fallback | The classification applied when no classifier condition is met: Valid, Invalid, or Error. |
| **CUSTOM BRANCHES** |  |
| **+ Add Custom Branch** | Adds a custom branch. Use custom branches to route the journey dynamically based on the outcome of the external token validation request. |
| **Custom branch row** | Configures an individual custom branch:**Condition**: An expression that determines when the journey follows this branch. For example, `response.status >= 400`.**Branch name**: A friendly name displayed in the journey editor.**Branch ID**: The identifier used to reference the branch in the journey. This field is required.**Branch type**: The outcome represented by the branch. Select `Success`, `Error`, or `Warning`. This field is required and defaults to `Error`. |