API Reference

Overview¶

Manage Identifiers and Omni Policies programmatically through the Metadata Service (MDS) REST APIs.

Authentication¶

All Metadata Service (MDS) API calls in this reference — Identifiers, Omni Policies, and the enforcement endpoints below — must be authenticated. On Self-Managed, send a bearer token in the Authorization header. On Data Plane and PrivaceraCloud, use an API key in the request URL. Requests without valid credentials, or on Self-Managed with a token that doesn't carry the required scope, are rejected.

1
2
3

POST <MDS-URL>/api/v2/metadata/omni-policies/enforcement/grant-access/resources
Authorization: Bearer <token>
Content-Type: application/json

1

https://<apiserver-host>/api/<api-key>

1

https://<apiserver-host>/api/<api-key>/omni-metadata

1

GET https://<apiserver-host>/api/<api-key>/omni-metadata/api/v1/metadata/identifiers

1

https://<apiserver-host>/api/<api-key>

1

https://<apiserver-host>/api/<api-key>/omni-metadata

1

GET https://<apiserver-host>/api/<api-key>/omni-metadata/api/v1/metadata/identifiers

Identifier APIs¶

An Identifier is a reusable, named selection of users, columns, or rows. Create identifiers first, then reference the returned id when authoring policies.

Base path: /api/v1/metadata/identifiers

Common request body fields¶

Used by Create and Update.

Each item in identifiers:

Each controller:

Creating an Identifier via API¶

Create a reusable Identifier (User, Column, or Record) that policies can reference.

API Endpoint:

1

POST <MDS-URL>/api/v1/metadata/identifiers

Request Body: See common request body fields above.

Example Request (USER_IDENTIFIER):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "name": "Employees",
  "description": "All employees",
  "type": "USER_IDENTIFIER",
  "identifiers": [
    {
      "description": "Employee user type",
      "controllers": [
        {
          "type_service": "ALL",
          "query": "USER.userType == 'EMPLOYEE'"
        }
      ]
    }
  ]
}

Example Request (RECORD_IDENTIFIER):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "name": "Allowed Properties by Region Access",
  "description": "Properties matching the requesting user's region",
  "type": "RECORD_IDENTIFIER",
  "identifiers": [
    {
      "description": "Snowflake region filter",
      "controllers": [
        {
          "type_service": "privacera_snowflake",
          "query": "obj.region_name = '${{USER.region}}'"
        }
      ]
    }
  ]
}

Example Request (COLUMN_IDENTIFIER):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Sensitive financial columns",
  "description": "Columns tagged SENSITIVE_FINANCIAL",
  "type": "COLUMN_IDENTIFIER",
  "identifiers": [
    {
      "controllers": [
        {
          "type_service": "ALL",
          "query": "HAS_TAG('SENSITIVE_FINANCIAL')"
        }
      ]
    }
  ]
}

HTTP Status Codes:

• 201 Created: Identifier created successfully
• 400 Bad Request: Validation error (missing name, invalid type, blank query, invalid type_service)

Response Fields:

• id: Identifier vertex ID — save this for policy authoring
• name: Identifier name
• type: USER_IDENTIFIER, COLUMN_IDENTIFIER, or RECORD_IDENTIFIER
• description: Description
• status: Status (for example, ACTIVE)
• identifier: Array of definition blocks
  • description: Description of the block
  • controllers: Array of rules
    • type_service: Service scope (ALL or a service name)
    • query: Filter expression
• createdTime / updatedTime: Creation and last-update time as Unix epoch milliseconds
• createdBy / updatedBy: Audit fields

On failed requests, the response may also include errorCode and message.

Example Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Employees",
  "type": "USER_IDENTIFIER",
  "description": "All employees",
  "status": "ACTIVE",
  "identifier": [
    {
      "description": "Employee user type",
      "controllers": [
        {
          "type_service": "ALL",
          "query": "USER.userType == 'EMPLOYEE'"
        }
      ]
    }
  ],
  "createdTime": 1780294519989,
  "updatedTime": 1780294519989,
  "createdBy": "admin@example.com",
  "updatedBy": "admin@example.com"
}

Listing Identifiers via API¶

List and search identifiers. Use optional filters to narrow results by type or name, and use pagination parameters to retrieve additional pages.

API Endpoint:

1

GET <MDS-URL>/api/v1/metadata/identifiers

Query Parameters:

• types (optional): Filter by identifier type (USER_IDENTIFIER, COLUMN_IDENTIFIER, RECORD_IDENTIFIER). Repeat the parameter to include multiple types (OR logic). Example: types=USER_IDENTIFIER&types=RECORD_IDENTIFIER
• search (optional): Case-insensitive name search
• sortBy (optional): Sort field — name, type, createdat, updatedat (default: name)
• sortOrder (optional): Sort direction — asc or desc (default: asc)
• page (optional): Page number for pagination (zero-based, default: 0)
• size (optional): Number of identifiers per page (default: 25, maximum: 1000)

Example Request:

1

GET <MDS-URL>/api/v1/metadata/identifiers?types=USER_IDENTIFIER&search=Employee&sortBy=name&sortOrder=asc&page=0&size=25

Response Fields:

• eventTime: Timestamp of the operation (epoch milliseconds)
• status: Status of the operation (for example, SUCCESS)
• totalCount: Total number of matching identifiers across all pages
• number: Current page number (zero-based)
• pageSize: Number of items returned on this page
• totalPages: Total number of pages
• hasNext: true when another page is available; increment page to fetch it
• hasPrevious: true when a previous page is available
• content: Array of identifier objects (same fields as the create response)
  • id: Identifier vertex ID
  • name: Identifier name
  • type: Identifier type
  • description: Description
  • status: Status
  • identifier: Array of definition blocks with controllers
  • createdTime / updatedTime: Creation and last-update time as Unix epoch milliseconds
  • createdBy / updatedBy: Audit fields
• filters: Echo of filters applied for this request (for example, types, search)
• sortBy: Field used for sorting
• sortOrder: Sort direction

On failed requests, the response may also include errorCode and message.

Example Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{
  "eventTime": 1780294519989,
  "status": "SUCCESS",
  "totalCount": 1,
  "number": 0,
  "pageSize": 25,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false,
  "content": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Employees",
      "type": "USER_IDENTIFIER",
      "description": "All employees",
      "status": "ACTIVE",
      "identifier": [
        {
          "controllers": [
            {
              "type_service": "ALL",
              "query": "USER.userType == 'EMPLOYEE'"
            }
          ]
        }
      ],
      "createdTime": 1780294519989,
      "updatedTime": 1780294519989
    }
  ],
  "filters": {
    "types": ["USER_IDENTIFIER"],
    "search": "Employee"
  },
  "sortBy": "name",
  "sortOrder": "asc"
}

Pagination:

When hasNext is true, more results are available. Request the next page by incrementing the page query parameter while keeping the same size and filters.

Retrieving an Identifier by ID via API¶

Retrieve a single identifier by its vertex ID.

API Endpoint:

1

GET <MDS-URL>/api/v1/metadata/identifiers/{id}

Path Parameters:

• id (required): Identifier vertex ID

Example Request:

1

GET <MDS-URL>/api/v1/metadata/identifiers/a1b2c3d4-e5f6-7890-abcd-ef1234567890

HTTP Status Codes:

• 200 OK: Identifier found
• 400 Bad Request: Identifier ID is blank
• 404 Not Found: No identifier with the given ID

Response Fields: Same as the create response.

Updating an Identifier via API¶

Update an existing identifier. If the number of affected policy resources exceeds the async threshold, the entity update and Ranger re-sync are queued as a background job.

API Endpoint:

1

PUT <MDS-URL>/api/v1/metadata/identifiers/{id}

Path Parameters:

• id (required): Identifier vertex ID

Request Body: Same structure as create. All required fields (name, type, identifiers) must be provided.

Example Request:

1
2

PUT <MDS-URL>/api/v1/metadata/identifiers/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Employees",
  "description": "All employees",
  "type": "USER_IDENTIFIER",
  "identifiers": [
    {
      "controllers": [
        {
          "type_service": "ALL",
          "query": "USER.userType == 'EMPLOYEE'"
        }
      ]
    }
  ]
}

HTTP Status Codes:

• 200 OK: Update and Ranger re-sync completed inline
• 202 Accepted: Update queued as a background job
• 400 Bad Request: Validation error
• 404 Not Found: Identifier not found

Response Fields (inline update — 200): Same as the create response.

Response Fields (async update — 202):

• job_id: Background job ID — poll the job endpoint for completion status
• data: Snapshot of the identifier at the time the job was queued

Example Response (202 Accepted):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "job_id": 42,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Employees",
    "type": "USER_IDENTIFIER",
    "status": "ACTIVE",
    "identifier": [
      {
        "controllers": [
          {
            "type_service": "ALL",
            "query": "USER.userType == 'EMPLOYEE'"
          }
        ]
      }
    ]
  }
}

Deleting an Identifier via API¶

Delete an identifier. Deletion is rejected if the identifier is still referenced by one or more Omni Policies.

API Endpoint:

1

DELETE <MDS-URL>/api/v1/metadata/identifiers/{id}

Path Parameters:

• id (required): Identifier vertex ID

Example Request:

1

DELETE <MDS-URL>/api/v1/metadata/identifiers/a1b2c3d4-e5f6-7890-abcd-ef1234567890

HTTP Status Codes:

• 204 No Content: Identifier deleted successfully (no response body)
• 202 Accepted: Delete queued as a background job — response body is { "job_id": <number>, "data": null }; poll the job endpoint for completion
• 400 Bad Request: Identifier ID is blank
• 404 Not Found: Identifier not found
• 409 Conflict: Identifier is still referenced by one or more policies — remove it from all policies first

Identifier examples¶

The examples below use the Acme scenarios. Create these identifiers first, then use the returned id values when authoring policies.

USER_IDENTIFIER¶

Employees¶

Used by the Employee portfolio access policy. Selects all employees.

UI query: USER.userType == 'EMPLOYEE'

API Endpoint:

1

POST <MDS-URL>/api/v1/metadata/identifiers

Example Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "name": "Employees",
  "description": "All employees",
  "type": "USER_IDENTIFIER",
  "identifiers": [
    {
      "description": "Employee user type",
      "controllers": [
        {
          "type_service": "ALL",
          "query": "USER.userType == 'EMPLOYEE'"
        }
      ]
    }
  ]
}

Regional Managers¶

Used by the Allowed properties to view row-filter policy.

UI query: IS_IN_ROLE('manager')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Regional Managers",
  "description": "Users with the manager role",
  "type": "USER_IDENTIFIER",
  "identifiers": [
    {
      "controllers": [
        {
          "type_service": "ALL",
          "query": "IS_IN_ROLE('manager')"
        }
      ]
    }
  ]
}

Identify Offshore users¶

Used by the Texas row-filter policies for offshore users.

UI query: USER.location == 'offshore'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Identify Offshore users",
  "description": "Users located offshore",
  "type": "USER_IDENTIFIER",
  "identifiers": [
    {
      "controllers": [
        {
          "type_service": "ALL",
          "query": "USER.location == 'offshore'"
        }
      ]
    }
  ]
}

COLUMN_IDENTIFIER¶

Sensitive financial columns¶

Used by the Redact sensitive data masking policy on REAL_ESTATE_TENANTS.

UI query: HAS_TAG('SENSITIVE_FINANCIAL')

API Endpoint:

1

POST <MDS-URL>/api/v1/metadata/identifiers

Example Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Sensitive financial columns",
  "description": "Columns tagged SENSITIVE_FINANCIAL",
  "type": "COLUMN_IDENTIFIER",
  "identifiers": [
    {
      "controllers": [
        {
          "type_service": "ALL",
          "query": "HAS_TAG('SENSITIVE_FINANCIAL')"
        }
      ]
    }
  ]
}

RECORD_IDENTIFIER¶

Allowed Properties by Region Access¶

Used by the Allowed properties to view row-filter policy. Regional managers see only properties in their region.

UI query: obj.region_name = '${{USER.region}}'

API Endpoint:

1

POST <MDS-URL>/api/v1/metadata/identifiers

Example Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "name": "Allowed Properties by Region Access",
  "description": "Properties matching the requesting user's region",
  "type": "RECORD_IDENTIFIER",
  "identifiers": [
    {
      "description": "Snowflake region filter",
      "controllers": [
        {
          "type_service": "privacera_snowflake",
          "query": "obj.region_name = '${{USER.region}}'"
        }
      ]
    }
  ]
}

Identify Texas data¶

Used by Restrict Texas data from offshore users. Resolves the STATE column by tag at query time.

UI query: obj.${{TAG_GET_CHILD_RES('STATE')}} = 'TX'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "name": "Identify Texas data",
  "description": "Rows in Texas",
  "type": "RECORD_IDENTIFIER",
  "identifiers": [
    {
      "description": "Snowflake Texas filter",
      "controllers": [
        {
          "type_service": "privacera_snowflake",
          "query": "obj.${{TAG_GET_CHILD_RES('STATE')}} = 'TX'"
        }
      ]
    }
  ]
}

Identify Data with consent¶

Used by Texas data for offshore users with consent.

UI query: obj.consent_given = 'true'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Identify Data with consent",
  "description": "Rows where consent has been given",
  "type": "RECORD_IDENTIFIER",
  "identifiers": [
    {
      "controllers": [
        {
          "type_service": "privacera_snowflake",
          "query": "obj.consent_given = 'true'"
        }
      ]
    }
  ]
}

Omni Policy APIs (CRUD)¶

An Omni Policy controls who is governed, which data it applies to, and what action is taken. Create identifiers first, then reference their id values in the policy identifiers map and in whoQuery, dataQuery, and dataFiltersQuery. See Policies for the authoring model these operations manage.

Base path: /api/v1/metadata/omni-policies

Common request body fields¶

Used by Create and Update (OmniPolicyRequest).

identifiers map keys:

Each key holds an array of identifier vertex IDs from Create identifier responses. Put those same IDs in whoQuery, dataQuery, and dataFiltersQuery. At Ranger sync time, MDS replaces each ID with the Identifier's stored query. To combine multiple identifiers, join their IDs with AND or OR (for example, "<id1> AND <id2>").

applyPolicy object:

Asset type values:

Principal type values: USER, GROUP, ROLE. Use GROUP with name public for everyone.

Creating an Omni Policy via API¶

API Endpoint:

1

POST <MDS-URL>/api/v1/metadata/omni-policies

Request Body: See common request body fields above.

Example Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Restrict Texas data from offshore users",
  "type": "RLF",
  "status": "ACTIVE",
  "actions": [{ "action": "DENY" }],
  "identifiers": {
    "user_identifier": ["<offshore-users-id>"],
    "record_identifier": ["<texas-data-id>"]
  },
  "whoQuery": "<offshore-users-id>",
  "dataFiltersQuery": "<texas-data-id>",
  "applyPolicy": {
    "assets": [{ "type": "TAG", "id": "CUSTOMER_DATA" }]
  }
}

Replace <offshore-users-id> and <texas-data-id> (in both identifiers and the matching query fields) with the id values from Create identifier. This RLF example shows whoQuery and dataFiltersQuery. For dataQuery (column identifiers), see the MASKING example under Omni Policy examples. For ACCESS examples, see the same section.

HTTP Status Codes:

• 201 Created: Policy created synchronously — response body is the full policy object
• 202 Accepted: Policy creation queued as async job — response body is { "job_id": <number>, "data": null }; poll the job endpoint for completion
• 400 Bad Request: Validation error

Response Fields:

• id: Policy vertex ID
• name: Policy name
• type: ACCESS, MASKING, or RLF
• description: Description
• policyStatus: DRAFT, ACTIVE, or INACTIVE
• actions: Array of action definitions
• identifiers: Linked identifier objects (on single-fetch responses)
• whoQuery / dataQuery / dataFiltersQuery: Identifier vertex IDs stored on the policy (MDS resolves them to Identifier queries during Ranger sync)
• applyPolicy: Attached assets and principals
• createdAt / updatedAt: Creation and last-update time as Unix epoch milliseconds (numeric; not an ISO datetime string)
• createdBy / updatedBy: Audit fields
• summary: Human-readable summary

Example Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "id": "policy-001",
  "eventTime": 1780294519989,
  "status": "SUCCESS",
  "name": "Restrict Texas data from offshore users",
  "type": "RLF",
  "policyStatus": "ACTIVE",
  "actions": [{ "action": "DENY" }],
  "identifiers": [
    {
      "id": "<offshore-users-id>",
      "name": "Identify Offshore users",
      "type": "USER_IDENTIFIER"
    },
    {
      "id": "<texas-data-id>",
      "name": "Identify Texas data",
      "type": "RECORD_IDENTIFIER"
    }
  ],
  "whoQuery": "<offshore-users-id>",
  "dataFiltersQuery": "<texas-data-id>",
  "applyPolicy": {
    "assets": [{ "type": "TAG", "id": "CUSTOMER_DATA" }],
    "principals": []
  },
  "createdAt": 1780294519989,
  "updatedAt": 1780294519989
}

Listing Omni Policies via API¶

API Endpoint:

1

GET <MDS-URL>/api/v1/metadata/omni-policies

Query Parameters:

• search (optional): Search by policy name pattern
• type (optional): Filter by type — ACCESS, MASKING, or RLF
• status (optional): Filter by status — DRAFT, ACTIVE, or INACTIVE
• sortBy (optional): name, type, createdat, updatedat (default: name)
• sortOrder (optional): asc or desc (default: asc)
• page (optional): Page number (zero-based, default: 0)
• size (optional): Page size (default: 25, maximum: 1000)

Example Request:

1

GET <MDS-URL>/api/v1/metadata/omni-policies?type=RLF&status=ACTIVE&page=0&size=25

Response Fields:

• eventTime, status, totalCount, number, pageSize, totalPages, hasNext, hasPrevious
• content: Array of policy summary objects (name, type, policyStatus, createdAt, updatedAt)
• filters, sortBy, sortOrder

Retrieving an Omni Policy by ID via API¶

1

GET <MDS-URL>/api/v1/metadata/omni-policies/{id}

HTTP Status Codes: 200 OK, 400 Bad Request, 404 Not Found

Response Fields: Full policy object including identifiers and applyPolicy.

Updating an Omni Policy via API¶

1

PUT <MDS-URL>/api/v1/metadata/omni-policies/{id}

Request Body: Same structure as create.

HTTP Status Codes: 200 OK, 202 Accepted, 400 Bad Request, 404 Not Found

Response Fields (202): job_id, data (policy snapshot at queue time)

Patching Omni Policy metadata via API¶

Update only name, description, or summary. Does not trigger a Ranger sync.

1

PATCH <MDS-URL>/api/v1/metadata/omni-policies/{id}

1
2
3
4

{
  "name": "Updated policy name",
  "description": "Updated description"
}

At least one of name, description, or summary must be provided.

HTTP Status Codes: 200 OK, 400 Bad Request, 404 Not Found

Activating and deactivating an Omni Policy via API¶

Activate (DRAFT → ACTIVE):

1

PATCH <MDS-URL>/api/v1/metadata/omni-policies/{id}/activate

Deactivate (ACTIVE → INACTIVE):

1

PATCH <MDS-URL>/api/v1/metadata/omni-policies/{id}/deactivate

No request body. The policy must pass ACTIVE validation rules before activation succeeds.

HTTP Status Codes: 200 OK, 202 Accepted, 400 Bad Request, 404 Not Found

Deleting an Omni Policy via API¶

1

DELETE <MDS-URL>/api/v1/metadata/omni-policies/{id}

HTTP Status Codes: 200 OK, 202 Accepted, 400 Bad Request, 404 Not Found

Omni Policy query APIs¶

Read-only endpoints for inspecting the assets and coverage of a policy.

Get assets for a policy¶

Returns every asset attached to a policy via HAS_POLICY_ASSET edges, grouped by type.

1

GET <MDS-URL>/api/v1/metadata/omni-policies/{id}/assets

Path Parameters:

• id (required): Omni policy vertex ID

Response Fields:

• policyId: Policy vertex ID
• tags: Array of tag assets (name, vertex ID)
• resources: Array of resource assets (vertex ID, resource path, type, service name)
• dataProducts: Array of data-product assets (name, status, description, default tags)

All three lists are always present (empty when no assets of that type are attached).

HTTP Status Codes: 200 OK, 400 Bad Request, 404 Not Found

Get resource count for a policy¶

Returns the policy identity and the number of assets it governs.

1

GET <MDS-URL>/api/v1/metadata/omni-policies/{id}/summary

Response Fields: policyId, policyName, policyType, policyStatus, resourceCount, userCount

List policies by asset¶

Returns policies linked to a given asset (via HAS_POLICY_ASSET). Use this endpoint to list every Omni policy that applies to a data product, tag, or resource.

1

GET <MDS-URL>/api/v1/metadata/omni-policies/by-asset/{assetId}

Path Parameters:

• assetId (required): Asset identifier — use the same id value as in applyPolicy.assets. Unlike the enforcement APIs, this endpoint has no {type} segment; pass the asset identifier directly.

Query Parameters:

• name (optional): Case-insensitive policy-name prefix filter
• type (optional): ACCESS, MASKING, or RLF
• sortBy (optional): name (default), type, createdAt, updatedAt, status
• sortOrder (optional): asc or desc
• page (optional): Zero-based page number (default: 0)
• size (optional): Page size (default: 25)

Example Requests:

1

GET <MDS-URL>/api/v1/metadata/omni-policies/by-asset/CUSTOMER_DATA?type=RLF&page=0&size=25

1

GET <MDS-URL>/api/v1/metadata/omni-policies/by-asset/dp-real-estate-portfolio

1

GET <MDS-URL>/api/v1/metadata/omni-policies/by-asset/privacera_snowflake/PS_SF_DB/OMNI_SCHEMA/OMNI_TABLE_1

Response Fields:

• eventTime, status, totalCount, number, pageSize, totalPages, hasNext, hasPrevious
• content: Array of policy objects (same fields as the create response)
• filters, sortBy, sortOrder

HTTP Status Codes: 200 OK, 400 Bad Request, 404 Not Found

Policy summary by identifier¶

Returns every policy referencing the identifier, each with its resource count, plus grand totals.

1

GET <MDS-URL>/api/v1/metadata/omni-policies/by-identifier/{identifierId}/summary

Response Fields:

• identifierId: Identifier vertex ID
• policyCount: Number of policies referencing this identifier
• totalResources / totalActiveResources: Distinct asset totals (all / ACTIVE only)
• resourceCountByType / activeResourceCountByType: Per-type counts (for example, { "MASKING": 15, "RLF": 10 })
• policies: Array of { policyId, policyName, policyType, policyStatus, resourceCount, userCount }

HTTP Status Codes: 200 OK, 400 Bad Request

Omni Policy enforcement APIs¶

Base path: /api/v1/metadata/omni-policies/enforcement

Grant or revoke Ranger policies on an asset, or manage direct access grants. The {type} path segment must be one of: tags, resources, data-products.

Grant / revoke policies¶

Push (grant) or remove (revoke) the Ranger policies defined by the supplied policy IDs on the asset.

1
2

POST <MDS-URL>/api/v1/metadata/omni-policies/enforcement/grant/{type}/{assetId}
POST <MDS-URL>/api/v1/metadata/omni-policies/enforcement/revoke/{type}/{assetId}

Request Body:

1
2
3

{
  "omniPolicyIds": ["<policy-id-1>", "<policy-id-2>"]
}

At least one policy ID is required.

Grant / revoke access¶

Create or delete GRANTS_PERMISSION_TO edges (asset → principals), then re-sync the Ranger ACCESS policy for the asset.

1
2

POST <MDS-URL>/api/v1/metadata/omni-policies/enforcement/grant-access/{type}/{assetId}
POST <MDS-URL>/api/v1/metadata/omni-policies/enforcement/revoke-access/{type}/{assetId}

Grant access — request body:

1
2
3
4
5
6
7
8

{
  "permission": "READ",
  "principals": {
    "users": ["david"],
    "groups": [],
    "roles": []
  }
}

permission must be READ or WRITE. At least one of users, groups, or roles must be non-empty.

Revoke access — request body:

1
2
3
4
5
6
7

{
  "principals": {
    "users": ["david"],
    "groups": [],
    "roles": []
  }
}

Omit permission on revoke. At least one of users, groups, or roles must be non-empty.

HTTP Status Codes: 200 OK, 400 Bad Request, 404 Not Found

List grant-access¶

Returns a paginated list of principals granted access on the asset, each with its permission.

1

GET <MDS-URL>/api/v1/metadata/omni-policies/enforcement/grant-access/{type}/{assetId}

Query Parameters: principalType (USER, GROUP, ROLE), search, sortBy (name, type, permission), sortOrder, page, size (max 200).

Grant / revoke access by resource path (v2)¶

Grants or revokes READ or WRITE access on a resource, identified by its service name and path, for one or more users, groups, or roles.

If the resource — or any part of the path leading to it — does not already exist, it is created automatically. For example, granting access on a table that has not been added yet also creates its parent schema or catalog first, if those do not exist either.

Base path: /api/v2/metadata/omni-policies/enforcement

1
2
3

POST <MDS-URL>/api/v2/metadata/omni-policies/enforcement/grant-access/resources
Authorization: Bearer <token>
Content-Type: application/json

1
2
3

POST <MDS-URL>/api/v2/metadata/omni-policies/enforcement/revoke-access/resources
Authorization: Bearer <token>
Content-Type: application/json

On Data Plane and PrivaceraCloud, omit the Authorization header and use the API-key URL, including /omni-metadata, in place of <MDS-URL>. See Authentication.

Grant access — request body¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "resource": {
    "serviceName": "privacera_databricks_unity_catalog",
    "resourcePath": "cat1/db1/table1",
    "serviceType": "DATABRICKS_UNITY_CATALOG",
    "resourceType": "TABLE"
  },
  "grant": {
    "permission": "READ",
    "principals": {
      "users": [],
      "groups": [],
      "roles": ["role1"]
    }
  }
}

resource:

grant:

Revoke access — request body¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "resource": {
    "serviceName": "privacera_databricks_unity_catalog",
    "resourcePath": "cat1/db1/table1",
    "serviceType": "DATABRICKS_UNITY_CATALOG",
    "resourceType": "TABLE"
  },
  "revoke": {
    "principals": {
      "users": [],
      "groups": [],
      "roles": ["role1"]
    }
  }
}

resource: same fields as above.

revoke:

Behavior¶

Grant and revoke are incremental¶

Grant and revoke operations affect only the principals specified in the request.

Granting access to a principal does not change access for other principals that already have access to the resource. Similarly, revoking access for one principal does not affect any other principal.

You do not need to send the complete list of principals with each request.

One permission per grant request¶

A grant request applies one permission value to all principals in the request.

For example, to grant READ to role1 and WRITE to role2, make two requests:

1
2
3
4
5
6

{
  "permission": "READ",
  "principals": {
    "roles": ["role1"]
  }
}

1
2
3
4
5
6

{
  "permission": "WRITE",
  "principals": {
    "roles": ["role2"]
  }
}

One resource per request¶

The resource field accepts a single resource. To grant the same access to multiple resources, make one request for each resource.

For example, to grant READ access to role1 on table1 and table2, make one request per resource, changing only resourcePath:

• cat1/db1/table1
• cat1/db1/table2

HTTP status codes¶

Masking function support API¶

Returns each masking function with the service types that support it (and those that do not), plus services with no masking support at all. Use it to check compatibility before choosing a masking action.

1

GET <MDS-URL>/api/v1/metadata/masking-functions/service-support

Response Fields:

• masking_functions: Map of masking function → { "supported": [services], "not_supported": [services] }
• services_without_masking_support: Services that support no masking functions

HTTP Status Codes: 200 OK

Omni Policy examples¶

The examples below use the Acme scenarios. Replace placeholder IDs with values from your environment and from the identifier examples above.

ACCESS — Employee portfolio access¶

Goal: Let all employees read the REAL_ESTATE_PORTFOLIO data product, so a new hire is covered automatically. whoQuery is the Employees user identifier ID; applyPolicy.assets scopes the policy to the data product.

1

POST <MDS-URL>/api/v1/metadata/omni-policies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "name": "Employee portfolio access",
  "description": "Employees can read the property portfolio",
  "type": "ACCESS",
  "status": "ACTIVE",
  "actions": [{ "action": "READ" }],
  "identifiers": {
    "user_identifier": ["<employees-id>"]
  },
  "whoQuery": "<employees-id>",
  "applyPolicy": {
    "assets": [{ "type": "DATA_PRODUCT", "id": "<real-estate-portfolio-id>" }]
  }
}

RLF — Allowed properties to view¶

Goal: Regional managers (david, emily) see only rows for their own region. dataFiltersQuery is the Allowed Properties by Region Access record identifier ID (that Identifier holds the row filter expression).

1

POST <MDS-URL>/api/v1/metadata/omni-policies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "name": "Allowed properties to view",
  "type": "RLF",
  "status": "ACTIVE",
  "actions": [{ "action": "ALLOW" }],
  "identifiers": {
    "record_identifier": ["<region-access-id>"]
  },
  "dataFiltersQuery": "<region-access-id>",
  "applyPolicy": {
    "assets": [{ "type": "DATA_PRODUCT", "id": "<real-estate-portfolio-id>" }],
    "principals": [
      { "type": "USER", "name": "david" },
      { "type": "USER", "name": "emily" }
    ]
  }
}

RLF — Restrict Texas data from offshore users¶

Goal: Hide Texas customer rows from offshore users across all tables tagged CUSTOMER_DATA. The DENY action drops matching rows. whoQuery and dataFiltersQuery are the offshore-user and Texas-data identifier IDs.

1

POST <MDS-URL>/api/v1/metadata/omni-policies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Restrict Texas data from offshore users",
  "type": "RLF",
  "status": "ACTIVE",
  "actions": [{ "action": "DENY" }],
  "identifiers": {
    "user_identifier": ["<offshore-users-id>"],
    "record_identifier": ["<texas-data-id>"]
  },
  "whoQuery": "<offshore-users-id>",
  "dataFiltersQuery": "<texas-data-id>",
  "applyPolicy": {
    "assets": [{ "type": "TAG", "id": "CUSTOMER_DATA" }]
  }
}

RLF — Texas data for offshore users with consent¶

Goal: Allow offshore users to see Texas rows, but only for customers who gave consent. Same scope as the previous policy; dataFiltersQuery is the consent record identifier ID.

1

POST <MDS-URL>/api/v1/metadata/omni-policies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "name": "Texas data for offshore users with consent",
  "type": "RLF",
  "status": "ACTIVE",
  "actions": [{ "action": "ALLOW" }],
  "identifiers": {
    "user_identifier": ["<offshore-users-id>"],
    "record_identifier": ["<consent-data-id>"]
  },
  "whoQuery": "<offshore-users-id>",
  "dataFiltersQuery": "<consent-data-id>",
  "applyPolicy": {
    "assets": [{ "type": "TAG", "id": "CUSTOMER_DATA" }]
  }
}

MASKING — Redact sensitive data¶

Goal: Mask sensitive financial columns for everyone (including data owners) on the REAL_ESTATE_TENANTS data product. MASK_NULL replaces values with NULL; dataQuery is the Sensitive financial columns column identifier ID. principals is GROUP public so it applies to all users.

1

POST <MDS-URL>/api/v1/metadata/omni-policies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "name": "Redact sensitive data",
  "description": "Mask sensitive financial columns for all users",
  "type": "MASKING",
  "status": "ACTIVE",
  "actions": [
    {
      "action": "MASK",
      "masking": { "type": "MASK_NULL" }
    }
  ],
  "identifiers": {
    "column_identifier": ["<sensitive-columns-id>"]
  },
  "dataQuery": "<sensitive-columns-id>",
  "applyPolicy": {
    "assets": [{ "type": "DATA_PRODUCT", "id": "<real-estate-tenants-id>" }],
    "principals": [{ "type": "GROUP", "name": "public" }]
  }
}

Draft-first workflow¶

1
2
3
4
5

{
  "name": "Employee portfolio access",
  "type": "ACCESS",
  "status": "DRAFT"
}

After adding actions, identifiers, and applyPolicy via PUT, activate:

1

PATCH <MDS-URL>/api/v1/metadata/omni-policies/<policy-id>/activate

Related topics¶

• Tags and Metadata
• Data Products