Integration Patterns

Prev Next

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 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": "<scope client id>",
    "clientSecret": "<scope client secret>",
    "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": "<data object Asset Type ID>",
  "policies": ["<ID of each Policy that applies>"],
  "dataObjectInstructions": {"allow": { }, "deny": { }},
  "dataEnforcementInstructions": [
    {"properties": ["<path>"], "operation": "<OPERATION>", "value": "<value>",
     "priority": 0, "condition": { }}
  ]
}]}

For how the Authorizer applies each part, see Policy Implementation.


Resolution Mode Requests

Resolution is the default, so the request can omit calculationType.

{
  "parameters": {
    "root": "result",
    "assetType": "<attributes Asset Type>",
    "maskString": "***",
    "filter": true
  },
  "plainid": {
    "entityTypeId": "<identity type>",
    "entityId": "<user id>",
    "clientId": "<client_id>",
    "clientSecret": "<client_secret>",
    "environment": { "resourceFullPath": ["<data mapper name>"] }
  },
  "json": "<JSON payload to process>"
}

Context Mode Requests

{
  "parameters": {
    "root": "result",
    "assetType": "<attributes Asset Type>",
    "calculationType": "context",
    "assetId": "<json path>",
    "protectedObject": "<data Asset Type>"
  },
  "plainid": {
    "entityTypeId": "<identity type>",
    "entityId": "<user id>",
    "clientId": "<client_id>",
    "clientSecret": "<client_secret>",
    "environment": { "resourceFullPath": ["<data mapper name>"] }
  },
  "json": "<JSON payload to process>"
}

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.

© 2026 PlainID LTD. All rights reserved.