Authorize Use

Type: Procedure

Request an authorization decision for a specific data operation. This is the core policy enforcement tool. It evaluates the requested operation against all applicable governance policies and returns a structured operator-facing decision with conditions, obligations, matched instructions, and evidence.

Use Cases

• An AI agent checks whether it can read from a sensitive table before executing a query
• An export workflow verifies authorization before sending data to an external system
• A data-sharing pipeline checks cross-jurisdiction rules before replicating data
• An agent asks "can I use this data for model training?" and gets a policy-backed answer

Input Parameters

Parameter	Type	Required	Description
table_name	string	Yes	Fully qualified table name (DB.SCHEMA.TABLE).
operation	string	Yes	The operation being requested. Common values include read, write, train, infer, export, and share.
intended_use	string	Yes	Canonical intended-use label such as analytics, reporting, marketing, ml_training, inference, external_sharing, or data_export. Natural-language requests should be normalized before calling the SQL tool directly.
actor_role	string	No	The Snowflake role or logical role performing the operation (e.g., DATA_ANALYST, ML_ENGINEER). If omitted, role-scoped rules are evaluated without an explicit actor role override.
columns	array	No	Array of column names involved in the operation. If omitted, the decision applies to all columns in the table.
destination	object	No	Where the data is going. Useful for export/share operations.
destination.system	string	No	Target system name (e.g., "Salesforce", "S3", "Tableau")
destination.jurisdiction	string	No	Destination jurisdiction (e.g., "EU", "US")
consumer_jurisdiction	string	No	Consumer jurisdiction used for transfer-governance evaluation.
context	object	No	Additional audit metadata logged with the decision. This does not change the policy outcome.
raw_request_text	string	No	Original natural-language request logged for audit when an app flow prepares the canonical request.
normalized_request	object	No	Structured request payload logged for audit.
normalization_meta	object	No	Metadata about request preparation, such as provider, confidence, warnings, or fallback usage.

Output Schema

Field	Type	Description
decision	string	One of: ALLOW, DENY, CONDITIONAL, UNKNOWN
decision_id	string	Unique identifier for this decision. Use with explain-why to retrieve the full audit trail.
confidence	string	Categorical confidence: high, medium, or low.
decision_score	number	Numeric score derived from the winning rule path. Useful for debugging and ranking, not as a separate decision.
decision_kind	string	Operator-facing decision category such as explicit_allow, enforced_deny, allow_with_pii_conditions, role_denied, or insufficient_context.
summary	string	Human-readable summary of the decision.
why_this_decision	string	Short explanation of the decisive policy path.
decisive_factors	array	Concise factors that determined the decision.
can_proceed_now	boolean	Whether the caller can proceed immediately without additional remediation.
must_do_before_proceeding	array	Required actions before proceeding.
blocked_by	array	Structured blockers for denied or unknown outcomes.
certainty_reason	string	Explanation for the categorical confidence level.
reason_codes	array	Machine-readable reason codes (e.g., ["PII_ACCESS_RESTRICTED", "CROSS_BORDER_BLOCKED"])
conditions	array	Conditions attached to a CONDITIONAL decision.
prohibitions	array	Decisive prohibition evidence for denied outcomes.
obligations	array	Follow-up actions the caller must satisfy or record.
next_actions	array	Suggested remediation or retry steps.
governing_policies	array	Compact summary of the policies/instructions that drove the outcome.
input_gaps	array	Missing request inputs that prevented a more definitive decision.
policy_gaps	array	Governance coverage gaps such as missing destination or jurisdiction rules.
matched_instructions	array	Decisive instruction summaries that justify the outcome.
matched_instruction_count	number	Number of decisive matched instructions returned.
matched_instructions[].instruction_id	string	Instruction identifier.
matched_instructions[].policy_name	string	Human-readable policy name for the instruction.
matched_instructions[].title	string	Instruction title.
matched_instructions[].description	string	Instruction description stored with the deployed policy.
matched_instructions[].impact	string	How the instruction affected the decision: allow, deny, conditional, or unknown.
matched_instructions[].match_reason	string	Short explanation of why the instruction matched.
evidence	array	Raw rule evidence that informed the decision.
applicable_policies	array	List of policy names that were in scope for the evaluation.
agent_action	object	Compact machine-actionable guidance for agents and pipelines.

Example Response

{
  "status": "ok",
  "data": {
    "decision": "DENY",
    "decision_id": "0133854f-c2ca-4e96-9cff-567f729935e4",
    "decision_kind": "enforced_deny",
    "can_proceed_now": false,
    "confidence": "medium",
    "certainty_reason": "High certainty because the decision came from a definitive matched rule path.",
    "summary": "Intended use \"marketing\" is explicitly prohibited by an enforced policy.",
    "why_this_decision": "An enforced prohibition matched this intended use and outranked all alternatives.",
    "decisive_factors": [
      "matched prohibited_use rule",
      "enforcement_mode=enforce",
      "deny outranks all"
    ],
    "blocked_by": ["enforced_prohibition"],
    "reason_codes": ["ENFORCED_PROHIBITION"],
    "conditions": [],
    "prohibitions": [
      {
        "instruction_id": "instr-usage-2",
        "policy_id": "policy-1",
        "rule_type": "prohibited_use",
        "scope_match": "table",
        "enforcement_mode": "enforce",
        "score": 100313
      }
    ],
    "obligations": [],
    "must_do_before_proceeding": [],
    "next_actions": [
      "Review the governing prohibition for allowed uses.",
      "Contact the data steward if this use needs an exception path."
    ],
    "governing_policies": [
      {
        "instruction_id": "instr-usage-2",
        "policy_id": "policy-1",
        "policy_name": "policy-1",
        "rule_type": "prohibited_use",
        "enforcement_mode": "enforce",
        "impact": "deny"
      }
    ],
    "input_gaps": [],
    "policy_gaps": [],
    "matched_instruction_count": 1,
    "matched_instructions": [
      {
        "instruction_id": "instr-usage-2",
        "instruction_type": "usage_guidance",
        "policy_id": "policy-1",
        "policy_name": "Privacy Policy",
        "title": "Restrict marketing use of customer data",
        "description": "Customer data cannot be used for marketing outreach or third-party sharing.",
        "priority": "high",
        "enforcement_mode": "enforce",
        "impact": "deny",
        "scope_match": "table",
        "rule_type": "prohibited_use",
        "match_reason": "matched intended_use=marketing at table scope"
      }
    ],
    "evidence": [
      {
        "instruction_id": "instr-usage-2",
        "policy_id": "policy-1",
        "rule_type": "prohibited_use",
        "scope_match": "table",
        "enforcement_mode": "enforce",
        "score": 100313
      }
    ]
  },
  "errors": []
}

SQL Examples

Basic authorization check

CALL METATATE_APP.CORE.AUTHORIZE_USE(
  OBJECT_CONSTRUCT(
    'table_name', 'ANALYTICS_DB.CORE.CUSTOMERS',
    'operation', 'read',
    'intended_use', 'reporting'
  )
);

Authorization for data export with destination

CALL METATATE_APP.CORE.AUTHORIZE_USE(
  OBJECT_CONSTRUCT(
    'table_name', 'ANALYTICS_DB.CORE.CUSTOMERS',
    'operation', 'export',
    'intended_use', 'data_export',
    'actor_role', 'DATA_ENGINEER',
    'columns', ARRAY_CONSTRUCT('NAME', 'EMAIL', 'COMPANY', 'ACCOUNT_STATUS'),
    'destination', OBJECT_CONSTRUCT(
      'system', 'Salesforce',
      'jurisdiction', 'US'
    ),
    'consumer_jurisdiction', 'EU'
  )
);

Check authorization for ML training

CALL METATATE_APP.CORE.AUTHORIZE_USE(
  OBJECT_CONSTRUCT(
    'table_name', 'ANALYTICS_DB.CORE.TRANSACTIONS',
    'operation', 'train',
    'intended_use', 'ml_training',
    'actor_role', 'ML_ENGINEER',
    'context', OBJECT_CONSTRUCT(
      'project', 'fraud_detection_v2',
      'environment', 'development'
    )
  )
);

JSON Request / Response (API)

Request:

{
  "method": "tools/call",
  "params": {
    "name": "authorize-use",
    "arguments": {
      "table_name": "ANALYTICS_DB.CORE.CUSTOMERS",
      "operation": "export",
      "intended_use": "data_export",
      "destination": {
        "system": "Salesforce",
        "jurisdiction": "US"
      }
    }
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"status\":\"ok\",\"data\":{\"decision\":\"CONDITIONAL\",\"decision_id\":\"58c4f4c8-87da-454f-920e-a92405616dac\",\"decision_kind\":\"allow_with_pii_conditions\",\"confidence\":\"medium\",\"summary\":\"Use \\\"analytics\\\" is permitted but table contains 2 PII column(s) requiring masking.\",\"why_this_decision\":\"The use is permitted, but PII handling requirements must be satisfied first.\",\"can_proceed_now\":false,\"matched_instruction_count\":1,\"matched_instructions\":[{\"instruction_id\":\"instr-usage-1\",\"policy_name\":\"Privacy Policy\",\"title\":\"Allow analytics for customer data\",\"description\":\"Customer data may be used for analytics and reporting.\",\"impact\":\"conditional\",\"match_reason\":\"matched intended_use=analytics at table scope\"}],\"must_do_before_proceeding\":[\"Apply masking or approved PII handling to affected columns before proceeding.\"],\"policy_gaps\":[],\"input_gaps\":[]},\"errors\":[]}"
    }
  ]
}

Try it in the app

Open Metatate and navigate to the Test Tools tab to run authorize-use interactively. The workbench supports both a structured request form and an AI-assisted natural-language preparation flow before the canonical SQL tool runs.