--- title: "Integration Patterns" slug: "integration-patterns-1" updated: 2026-11-15T17:30:21Z published: 2026-11-15T17:30:21Z canonical: "docs.plainid.io/integration-patterns-1" --- > ## 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. # Integration Patterns Services and API gateways integrate with the JSON Masking Authorizer through one REST endpoint, `POST /enforce`. The request carries the JSON payload, the identity of the caller, and the parameters that tell the Authorizer how to enforce. The Authorizer returns the authorized JSON. Contact the [PlainID Support Team](https://plainid.atlassian.net/servicedesk/customer/portals) for access to the Authorizer. ## How a Request Is Processed 1. The calling service sends a request to `http://<authorizer host>:<port>/enforce` with three parts: `parameters`, `plainid`, and `json`. 2. The Authorizer builds a PDP request from the configuration and the request parameters, and sends it to the PDP endpoint of the selected mode. 3. The Authorizer parses the PDP response and removes and masks objects and properties in the payload. 4. The Authorizer returns the authorized JSON to the calling service. In Data Instructions mode, the Authorizer also selects the data object in the PDP answer with `environment.resourceFullPath[0]`, removes the objects that the row rules exclude, and then applies the masking instructions to the objects that stay. --- ## Request Parameters `parameters` | Parameter | Modes | Description | | --- | --- | --- | | `calculationType` | All | `resolution` or empty (default), `dataInstructions`, or `context`. Any other value returns HTTP 400 and the PDP is not called. | | `root` | All | Path to the data objects in the payload. Empty means the whole payload. The root must resolve to an object or an array of objects. A `#` wildcard root such as `result.#.accounts` enforces every location it matches. | | `assetType` | All | Overrides the `assetType` configuration key for this request. | | `dataPropertyKey` | Data Instructions | The Asset Attribute of the masking catalog Assets that holds the property path. Overrides the `dataPropertyKey` configuration key for this request. | | `maskString` | Resolution | The string that masks string values. Defaults to the `maskString` configuration key. Non-string values become `null`. Ignored in Data Instructions mode (one WARN line). | | `filter` | Resolution | `true` uses the Policy Resolution privileges to filter whole objects. The filtering Policy must use an Action with the value `FILTER`. Ignored in Data Instructions mode (one WARN line). | | `assetId` | Context | Path in the payload (`gjson` syntax) of the Asset ID that the Authorizer sends to the PDP as Asset context. | | `protectedObject` | Context | The Asset Type of `assetId`, used in Policies as the protected resource. | --- `plainid` The Authorizer sends this object to the PDP as is. It also forwards the request headers (except hop-by-hop headers), so an Authorization header with a JWT can replace the client secret when the Scope uses JWT authentication. | Parameter | Description | | --- | --- | | `clientId` | The Scope's client ID, which represents the Application and its Policies for PDP evaluation. | | `clientSecret` | The Scope's client secret. You can omit it when the Scope uses JWT authentication and the request carries a valid JWT. | | `entityTypeId` | The Identity Type of the user who fetched the data. If you omit it, the PDP can use Identity Matching according to the Scope. | | `entityId` | The user ID. If you omit it, the PDP can use Identity Mappings according to the Identity Template. | | `environment.resourceFullPath` | Resolution mode: a Data Mapper name that maps logical Asset Attributes to physical JSON paths. Data Instructions mode: `resourceFullPath[0]` selects the data object Asset Type in the PDP answer. | | Other PDP parameters | Any valid PDP request parameter or flag. Not every flag affects how the Authorizer processes the response. | In Data Instructions mode the Authorizer always sets `includePriorityDecision` and `includeAccessPolicyId` to `true`. It does not support `assetContext` or `useOptimizedAssetContextResponse: true` in this mode, and returns HTTP 400 when they are present. --- `json` The full JSON payload as received from the data service. It must be a valid JSON object or JSON array. --- ## Calculation Types - **Resolution** (`resolution`, default): The Authorizer calls the PDP Policy Resolution endpoint and applies filtering and masking from the `access` and `privileges` sections. Use it when Policies depend on properties that exist in the JSON payload. - **Data Instructions** (`dataInstructions`): The Authorizer calls the PDP Data Instructions endpoint, which returns row rules (`dataObjectInstructions`) and masking instructions (`dataEnforcementInstructions`) for each data object. - **Context** (`context`): The Authorizer extracts Asset IDs from the payload and sends them as Asset context to the PDP User Access Token endpoint. Use it when Policies need Asset Attributes that the payload does not contain. --- ## Data Instructions Mode Requests ### Resource Types Sent to the PDP | The request has | The Authorizer sends | | --- | --- | | No `resourceTypes` and `resourceFullPath[0]` set (recommended) | `[{name: resourceFullPath[0]}, {name: assetType, dataPropertyKey: <config>}]`, or one entry when both names are equal. | | `resourceTypes` with entries | Those entries. The Authorizer adds `dataPropertyKey` to the entry named like the asset type, unless that entry carries its own. | | Neither | No resource types. | When you use Data Mappers, `resourceFullPath` holds a mapper path such as `db1.sc1.Accounts`. In that case, send `resourceTypes` yourself with the Asset Type names. ### Selecting the Data Object - The Authorizer applies the PDP entry whose `fullyQualifiedPath` equals `resourceFullPath[0]` (exact and case-sensitive) and ignores the others. - The Authorizer ignores extra values in `resourceFullPath` and logs one WARN line. - Without `resourceFullPath`, the Authorizer uses the single entry of the answer. Several entries return HTTP 400. ### Example Request ``` { "parameters": { "calculationType": "dataInstructions", "root": "accounts" }, "plainid": { "entityTypeId": "User", "entityId": "testuser1", "clientId": "", "clientSecret": "", "environment": { "resourceFullPath": ["JsonAccounts"] } }, "json": { "accounts": [ { "id": 1, "country": "IL", "email": "il@x.com" } ] } } ``` ### PDP Answer Structure The PDP Data Instructions endpoint answers with one entry per data object Asset Type: ``` {"response": [{ "fullyQualifiedPath": "", "policies": [""], "dataObjectInstructions": {"allow": { }, "deny": { }}, "dataEnforcementInstructions": [ {"properties": [""], "operation": "", "value": "", "priority": 0, "condition": { }} ] }]} ``` For how the Authorizer applies each part, see **[Policy Implementation](/v1/docs/policy-implementation-1)**. --- ## Resolution Mode Requests Resolution is the default, so the request can omit `calculationType`. ``` { "parameters": { "root": "result", "assetType": "", "maskString": "***", "filter": true }, "plainid": { "entityTypeId": "", "entityId": "", "clientId": "", "clientSecret": "", "environment": { "resourceFullPath": [""] } }, "json": "" } ``` ## Context Mode Requests ``` { "parameters": { "root": "result", "assetType": "", "calculationType": "context", "assetId": "", "protectedObject": "" }, "plainid": { "entityTypeId": "", "entityId": "", "clientId": "", "clientSecret": "", "environment": { "resourceFullPath": [""] } }, "json": "" } ``` --- ## Responses On success the Authorizer returns HTTP 200 with `Content-Type: application/json` and the enforced payload as the body. The `x-request-id` header carries the PDP request ID. Errors return plain text and never return the payload. ### Errors in Data Instructions Mode These are the errors the Authorizer returns for requests with `calculationType: "dataInstructions"`. | Status | Cause | Body | | --- | --- | --- | | 400 | Body is not valid JSON | The JSON error | | 400 | Unsupported `calculationType` | `unsupported calculation type` | | 400 | `assetContext` sent in Data Instructions mode | `plainID.assetContext and plainID.useOptimizedAssetContextResponse are not supported in the dataInstructions flow` | | 400 | `resourceFullPath[0]` is not a string | `environment.resourceFullPath must be a list of strings` | | 400 | No selector and several entries in the PDP answer | `data-instructions response holds 2 data objects (…); set environment.resourceFullPath` | | 400 | Selector matches no entry | `environment.resourceFullPath "X" matches no data object … (got: …)` | | 400 | `root` resolves to nothing | `parameters.root does not resolve: <root>` | | 400 | Target is a string, number, boolean, or `null` | `parameters.root must resolve to an object or an array: <root>` | | PDP status | The PDP answered with an error, for example 401 for a wrong secret | The PDP body | | 413 | Body larger than `maxBody` | | | 500 | PDP unreachable or no answer within 30 seconds | The connection error | | 500 | Malformed PDP answer | `malformed data-instructions response from <url>: …` | | 500 | An instruction path cannot be written | `apply the data instructions: …` | --- ## Supported JSON Path Syntax A path is a series of JSON property names separated by `.`, with these special characters: | Character | Meaning | | --- | --- | | `.` | Path separator between properties | | `#` | JSON array indicator | | `*` | Multi-character wildcard for a property name | | `?` | Single-character wildcard for a property name | | `\` | Escape character, so a special character counts as a regular character | Example payload: ``` { "name": {"first": "Tom", "last": "Anderson"}, "age": 37, "children": ["Sara", "Alex", "Jack"], "fav.movie": "Deer Hunter", "friends": [ {"first": "Dale", "last": "Murphy", "age": 44}, {"first": "Roger", "last": "Craig", "age": 68}, {"first": "Jane", "last": "Murphy", "age": 47} ] } ``` | Path | Result | Explanation | | --- | --- | --- | | `age` | `37` | A simple property | | `name.last` | `Anderson` | A nested property | | `children` | `["Sara","Alex","Jack"]` | The complete array | | `children.1` | `Alex` | An array element by index | | `friends.#.age` | `[44,68,47]` | A property inside an array of objects | | `friends.#` | `3` | The array length | | `child*.2` | `Jack` | Multi-character wildcard | | `name.fir?t` | `Tom` | Single-character wildcard | | `fav\.movie` | `Deer Hunter` | Escaped special character | > **Note:** In Data Instructions mode, property paths in masking instructions are relative to one data object and also support queries such as `items.#(type=="ssn")#.value`. Wildcards are not valid in these paths: escape `*` and `?` in key names with a backslash. An unescaped wildcard, or a modifier or pipe such as `name|@reverse`, fails the request with HTTP 500. --- ## Troubleshooting Data Instructions Mode Set `log.level: debug` and restart. The Authorizer then logs the data object it selects, the resource types it sends, and the PDP answer for each request. | Symptom | Check | | --- | --- | | Nothing is masked | The masking Policy has both the data object Ruleset (or All) and the catalog Assets. The Action values use `OPERATION::value::priority`. `assetType` matches the catalog Asset Type ID. The PDP answer lists `dataEnforcementInstructions`. | | A property is not masked | The Asset ID equals the property path relative to the data object, with the same case (`customerId`, not `customerid`). | | Objects are not filtered | The data object Asset Type is used for data filtering, its Attribute names match the JSON property names, and `root` points at the array. | | Everything is masked, or no object is returned | `leastPrivileges` is `true` and no Policy grants the object or the property. | | HTTP 400 `matches no data object` | `resourceFullPath[0]` must equal the data object Asset Type ID (or its Data Mapper path), case-sensitive. | | HTTP 401 from the PDP | Check the Scope client ID and secret, and that the Scope holds the Application. | | A property became `null` with a WARN line | A FUNCTION Action cannot run: the function is missing from `functions`, or it does not support the property's type. |