--- title: "Managing Identity Matchers" slug: "managing-identity-matchers" updated: 2026-06-30T12:53:29Z published: 2026-06-30T12:53:29Z canonical: "docs.plainid.io/managing-identity-matchers" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.plainid.io/llms.txt > Use this file to discover all available pages before exploring further. # Managing Identity Matchers Identity Matchers are key components for determining the Identity Template based on a defined virtual source, like a JWT claim or Header property. They allow for fine-tuned control over Template assignment and matching. The Identity Template Matcher uses a flexible JSONPath syntax for Identity Template matching, which allows you to determine which one is used for the Authorization decision calculation based on a received JWT or header. Similarly, the Identity ID Mapper is employed to map a source claim or header property value to be used as the Identity ID for Authorization calculation. Check out the detailed valid [JSON Path Structure and Examples](/v1/docs/managing-identity-matchers#json-path-structure-and-examples) section for more information. A common use case would be to use an Identity Token received from an IDP, where the issuer can be used with the Identity Template Matcher by matching the **iss** claim value and the token subject, **sub** claim value to be used as the source of the User ID. To ensure an effective Identity Template verification, it is crucial to maintain uniqueness in the defined matcher source and value. This helps avoid ambiguity and ensures accurate identification of the Identity Template. Ensure that you have matched the JSONPath to the Matcher Value to validate against the Identity Template. The Template is used only if the match is valid. If you do not have a Scope set up yet, see the guide on how to set one up [here](/v1/docs/managing-scopes){target=`_blank`}. **To set up an Identity Matcher:** 1. Next to the {{variable.Identities Workspace former}}, click on the **Settings** icon. 2. Click on the **Details** tile. 3. On the top-right of the Details screen, click **Edit** to modify the relevant fields. 4. Click **Save**. ## JWT Validation It is possible to perform JWT validation to ensure the integrity and authenticity of the tokens in the request. Ensure that the signature, expiration, and additional optional claims are valid to prevent invalid JWTs. The JWT validation is *optional* for the **Identity Template matching** and for **Identity Attributes mapping**. Each can be toggled based on the customer’s preference in accordance to their organization’s guidelines, the reliability of the JWT issuer, and their security preferences. Be aware that JWT validation can slightly increase overall performance due to the validation process. **To perform JWT Validation:** 1. In the Identities Workspace, click on the **Settings** icon. 2. In the Identity Template Settings, enable the relevant **JWT Validation toggles**. 3. Click **Save**. It is important to note that in case if the same JWT is used for different matchers/mappers, validation will take place only once. That is also the case when the Authorization JWT is used both for PDP Authentication and for Template matching and/or Attribute value extraction. Enabling JWT validations toggles requires users to set up JWT validation settings in the **Identities Workspace Settings**, which contains the Identity Template Matcher, Identity ID Mapper, and all other Identity Attributes Mappers. Users can set up multiple validation setting blocks in the event where different JWKs need to be set up. **To modify the JWT Validation Settings:** 1. Next to the Identities Workspace, click on the **Settings** icon. 2. Enable one or both toggles. 3. Click **JWT Settings**. 4. Input a **JWKs URL**. This URL is exposed by your IDP or other JWT Issuer, which will be used to fetch keys for the JWT signature validation. 5. Input a **Key Refresh Interval** (1-24 hours). 6. Input a Validation **Claim Key** and **Value** (optional). This field can always be updated. This is used as an extra validation step by checking for a Claim Key in your Authorization JWT and match its value. *Note: The Validation Claim Key and Value are verified after the JWKs URL and JWT expiration are validated first. Any value could be used as a claim value if you only wish to validate the existence of the claim regardless of its value.* ## JSONPath for Identity Attributes The Identity Attribute Mapper (Request Mapper) is utilized to map Attributes within the JWT or header to corresponding Identity Attributes. It plays a role in aligning incoming data with the Identity Template structure. Each Identity Attribute possesses the capability to utilize a JSONPath, a language designed for searching paths within JSON structures. This feature allows users to specify a JSONPath to navigate to a particular property within a JSON document, essentially providing the address of the desired property. Users can utilize JSONPath to define Attributes within the Authorization header JWT or any other header. This is used to extract and define Attributes from JSON structures to be utilized within the Identity resolution and Authorization processes, providing greater customization and adaptability. It's important to note that the default behavior for Identity Attributes is retained. If it is included as part of the request, it takes precedence over the JSONPath Mapper. If a JSONPath mapper is not defined and the value is not located, the Attribute is retrieved from an external source. *Note: There is no precedence for Identity Template and ID matching and mapping. In a Request Flow, the PDP will expect to receive values in the request body, while in a Matcher Flow, the PDP expects to match a valid template and Identity ID based on the matchers and mappers. Learn more about Request and Matcher flows in the [Identity Matching Types](/v1/docs/managing-scopes#identity-matching-types){target=`_blank`} section.* **To set a JSONPath:** 1. Next to the Identities Workspace, click on the **Settings** icon. 2. Click on the **Sources** tab. 3. Select the relevant Source (Request Mapper) to edit or create a new one. * Fill in the relevant fields and click **Save**. * Navigate to the Mapper Sets tab * Use the Source as one of your Linked Sources in the Mapper Set. * Adjust the mapping according to the [JSON Path Structure and Examples](/v1/docs/managing-identity-matchers#json-path-structure-and-examples) section. ## JSON Path Structure and Examples {{snippet.JSONPath Structure and Example}} :::(Internal) (Private notes) ### Using Virtual Data Sources in the Runtime Request Using Virtual Data Sources in the Runtime request provides a versatile and efficient way to handle Identity Attributes. This allows users to have more granular control over their Identities by determining which Identity Template, User ID, and Identity Attributes to use for the Authorization request. :::