Provisioning

The provisioning API covers three areas: JIT (Just-In-Time) Access for temporary privilege escalation, Agent Capabilities for granting structured permissions to AI agents, and Shadow Mode for risk-free deployment testing.

---

JIT Access

JIT access provides time-bounded privilege escalation. Requests go through an approval workflow before the elevated permissions take effect.

List JIT Access Requests

GET /v1/environments/{env_id}/jit-access

Lists all JIT access requests for the environment. Requires Owner, Admin, or Auditor role.

Request:

curl https://api.hatidata.com/v1/environments/env_prod_x1y2/jit-access \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "data": [
    {
      "request_id": "jit_a1b2c3",
      "requester_id": "usr_a4b5c6",
      "requester_email": "bob@acme.com",
      "current_role": "developer",
      "requested_role": "admin",
      "reason": "Need to update column masking policy for PCI audit",
      "duration_minutes": 60,
      "status": "pending",
      "requested_at": "2026-02-16T10:00:00Z",
      "expires_at": null
    },
    {
      "request_id": "jit_d4e5f6",
      "requester_id": "usr_g7h8i9",
      "requester_email": "eve@acme.com",
      "current_role": "analyst",
      "requested_role": "developer",
      "reason": "Deploy new dbt model to staging",
      "duration_minutes": 120,
      "status": "approved",
      "approved_by": "usr_x1y2z3",
      "requested_at": "2026-02-16T09:00:00Z",
      "expires_at": "2026-02-16T11:00:00Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "total": 2
  }
}

Request JIT Access

POST /v1/environments/{env_id}/jit-access

Submit a request for temporary privilege escalation. Any authenticated user can submit a request.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/jit-access \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_role": "admin",
    "reason": "Need to create new masking policy for GDPR compliance",
    "duration_minutes": 60
  }'

Response 201 Created:

{
  "request_id": "jit_j0k1l2",
  "requester_id": "usr_a4b5c6",
  "requested_role": "admin",
  "reason": "Need to create new masking policy for GDPR compliance",
  "duration_minutes": 60,
  "status": "pending",
  "requested_at": "2026-02-16T10:00:00Z"
}

Field	Type	Required	Description
requested_role	string	Yes	Target role: admin, developer, analyst
reason	string	Yes	Justification for the request
duration_minutes	integer	Yes	Duration of elevated access (max: 480)

Approve JIT Request

POST /v1/environments/{env_id}/jit-access/{request_id}/approve

Approves a pending JIT request. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/jit-access/jit_a1b2c3/approve \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "request_id": "jit_a1b2c3",
  "status": "approved",
  "approved_by": "usr_x1y2z3",
  "elevated_role": "admin",
  "effective_at": "2026-02-16T10:05:00Z",
  "expires_at": "2026-02-16T11:05:00Z"
}

Deny JIT Request

POST /v1/environments/{env_id}/jit-access/{request_id}/deny

Denies a pending JIT request. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/jit-access/jit_a1b2c3/deny \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Use the staging environment for policy testing"
  }'

Response 200 OK:

{
  "request_id": "jit_a1b2c3",
  "status": "denied",
  "denied_by": "usr_x1y2z3",
  "reason": "Use the staging environment for policy testing",
  "denied_at": "2026-02-16T10:10:00Z"
}

Revoke JIT Access

POST /v1/environments/{env_id}/jit-access/{request_id}/revoke

Immediately revokes an active JIT grant before its expiration. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/jit-access/jit_d4e5f6/revoke \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "request_id": "jit_d4e5f6",
  "status": "revoked",
  "revoked_by": "usr_x1y2z3",
  "original_expiry": "2026-02-16T11:00:00Z",
  "revoked_at": "2026-02-16T09:30:00Z"
}

---

Agent Capabilities

Agent capabilities provide structured, fine-grained permissions for AI agents beyond what API key scopes offer.

Grant Agent Capability

POST /v1/environments/{env_id}/agent-capabilities

Grants specific capabilities to an agent. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/agent-capabilities \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "data-analyst-v2",
    "capabilities": {
      "allowed_tables": ["public.customers", "public.orders", "public.products"],
      "allowed_operations": ["SELECT"],
      "max_queries_per_hour": 500,
      "max_rows_per_query": 10000,
      "column_restrictions": {
        "public.customers": {
          "denied_columns": ["ssn", "credit_card"]
        }
      }
    },
    "expires_at": "2026-03-16T00:00:00Z"
  }'

Response 201 Created:

{
  "grant_id": "acg_m3n4o5",
  "agent_id": "data-analyst-v2",
  "capabilities": {
    "allowed_tables": ["public.customers", "public.orders", "public.products"],
    "allowed_operations": ["SELECT"],
    "max_queries_per_hour": 500,
    "max_rows_per_query": 10000,
    "column_restrictions": {
      "public.customers": {
        "denied_columns": ["ssn", "credit_card"]
      }
    }
  },
  "expires_at": "2026-03-16T00:00:00Z",
  "granted_by": "usr_x1y2z3",
  "granted_at": "2026-02-16T10:00:00Z"
}

List Agent Capabilities

GET /v1/environments/{env_id}/agent-capabilities

Lists all agent capability grants. Requires Owner or Admin role.

Request:

curl "https://api.hatidata.com/v1/environments/env_prod_x1y2/agent-capabilities?agent_id=data-analyst-v2" \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "data": [
    {
      "grant_id": "acg_m3n4o5",
      "agent_id": "data-analyst-v2",
      "capabilities": {
        "allowed_tables": ["public.customers", "public.orders", "public.products"],
        "allowed_operations": ["SELECT"],
        "max_queries_per_hour": 500,
        "max_rows_per_query": 10000
      },
      "usage": {
        "queries_this_hour": 42,
        "total_queries": 3200
      },
      "status": "active",
      "expires_at": "2026-03-16T00:00:00Z",
      "granted_at": "2026-02-16T10:00:00Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "total": 1
  }
}

Revoke Agent Capability

DELETE /v1/environments/{env_id}/agent-capabilities/{grant_id}

Revokes an agent capability grant. Requires Owner or Admin role.

Request:

curl -X DELETE https://api.hatidata.com/v1/environments/env_prod_x1y2/agent-capabilities/acg_m3n4o5 \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "grant_id": "acg_m3n4o5",
  "agent_id": "data-analyst-v2",
  "revoked": true,
  "revoked_by": "usr_x1y2z3",
  "revoked_at": "2026-02-16T12:00:00Z"
}

---

Shadow Mode

Shadow Mode allows you to test HatiData against your existing data warehouse without affecting production traffic. Queries are replayed against HatiData and results are compared.

Start Shadow Mode

POST /v1/environments/{env_id}/shadow-mode/start

Starts a shadow mode session. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/shadow-mode/start \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "snowflake",
    "duration_hours": 24,
    "sample_rate": 0.1
  }'

Response 201 Created:

{
  "session_id": "shadow_p6q7r8",
  "status": "running",
  "source": "snowflake",
  "sample_rate": 0.1,
  "started_at": "2026-02-16T10:00:00Z",
  "ends_at": "2026-02-17T10:00:00Z"
}

Get Shadow Mode Status

GET /v1/environments/{env_id}/shadow-mode/status

Returns the current shadow mode session status and statistics.

Request:

curl https://api.hatidata.com/v1/environments/env_prod_x1y2/shadow-mode/status \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "session_id": "shadow_p6q7r8",
  "status": "running",
  "statistics": {
    "queries_replayed": 4200,
    "queries_matched": 4150,
    "queries_mismatched": 35,
    "queries_failed": 15,
    "match_rate": 0.988,
    "avg_latency_source_ms": 450,
    "avg_latency_hatidata_ms": 12
  },
  "started_at": "2026-02-16T10:00:00Z",
  "ends_at": "2026-02-17T10:00:00Z",
  "elapsed_hours": 4.5
}

Upload Query Log

POST /v1/environments/{env_id}/shadow-mode/upload

Uploads a query log file for shadow mode replay. Accepts JSONL format with one query per line.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/shadow-mode/upload \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/jsonl" \
  --data-binary @query_log.jsonl

Response 202 Accepted:

{
  "upload_id": "upl_s9t0u1",
  "queries_received": 15000,
  "status": "queued",
  "estimated_replay_minutes": 45
}

Replay Queries

POST /v1/environments/{env_id}/shadow-mode/replay

Triggers replay of uploaded queries against HatiData.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/shadow-mode/replay \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upl_s9t0u1",
    "concurrency": 10
  }'

Response 202 Accepted:

{
  "replay_id": "rpl_v2w3x4",
  "upload_id": "upl_s9t0u1",
  "status": "running",
  "concurrency": 10,
  "started_at": "2026-02-16T11:00:00Z"
}

Get Shadow Mode Report

GET /v1/environments/{env_id}/shadow-mode/report

Returns a comprehensive comparison report for the shadow mode session.

Request:

curl https://api.hatidata.com/v1/environments/env_prod_x1y2/shadow-mode/report \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "session_id": "shadow_p6q7r8",
  "summary": {
    "total_queries": 15000,
    "matched": 14850,
    "mismatched": 100,
    "failed": 50,
    "match_rate": 0.990,
    "latency_improvement": "37.5x"
  },
  "mismatches": [
    {
      "query": "SELECT LISTAGG(name, ',') FROM users GROUP BY dept",
      "reason": "Function not yet supported",
      "category": "unsupported_function"
    }
  ],
  "performance": {
    "p50_source_ms": 350,
    "p50_hatidata_ms": 8,
    "p95_source_ms": 2100,
    "p95_hatidata_ms": 45,
    "p99_source_ms": 8500,
    "p99_hatidata_ms": 120
  }
}

Stop Shadow Mode

POST /v1/environments/{env_id}/shadow-mode/stop

Stops the active shadow mode session.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/shadow-mode/stop \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "session_id": "shadow_p6q7r8",
  "status": "stopped",
  "stopped_at": "2026-02-16T14:00:00Z",
  "final_statistics": {
    "queries_replayed": 8500,
    "match_rate": 0.988
  }
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid parameters
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient role (must be Owner or Admin)
404	NOT_FOUND	Resource not found
409	CONFLICT	Shadow mode session already active
422	AGENT_NOT_FOUND	Referenced agent_id does not exist