Access API

The Access API enables AI systems to request governed access to datasets, ensuring compliance with data holder policies and automatically generating evidence.

API endpoints

Request Access

POST https://api.xase.ai/v1/access

# Request Body
{
  "dataset_id": "dataset_medical_records_2025",
  "purpose": "model-training",
  "model_id": "diagnostic-model-v2",
  "duration": "30d",
  "metadata": {
    "project": "Medical Diagnosis Improvement",
    "requester_notes": "Training on anonymized patient data"
  }
}

# Response (200 OK)
{
  "session_id": "sess_7f6e5d4c",
  "dataset_id": "dataset_medical_records_2025",
  "status": "ACTIVE",
  "created_at": "2026-01-15T14:30:00Z",
  "expires_at": "2026-02-14T14:30:00Z",
  "policy_id": "policy_medical_research",
  "policy_version": "1.2"
}

This endpoint initiates a new access request and performs policy evaluation.

If approved, a new session is created and returned.

If rejected, an error response is returned with the specific policy violation.

Get Access Status

GET https://api.xase.ai/v1/access/{session_id}

# Response (200 OK)
{
  "session_id": "sess_7f6e5d4c",
  "dataset_id": "dataset_medical_records_2025",
  "status": "ACTIVE",  // ACTIVE, PENDING, EXPIRED, REVOKED
  "created_at": "2026-01-15T14:30:00Z",
  "expires_at": "2026-02-14T14:30:00Z",
  "usage_stats": {
    "records_accessed": 12547,
    "operations_performed": 89,
    "last_access": "2026-01-15T16:45:23Z"
  }
}

List Access Sessions

GET https://api.xase.ai/v1/access?dataset_id=dataset_medical_records_2025&status=ACTIVE

# Query Parameters
# dataset_id (optional) - Filter by dataset ID
# status (optional) - Filter by status (ACTIVE, PENDING, EXPIRED, REVOKED)
# created_after (optional) - Filter by creation date
# created_before (optional) - Filter by creation date
# limit (optional) - Limit results (default: 20, max: 100)
# offset (optional) - Pagination offset

# Response (200 OK)
{
  "data": [
    {
      "session_id": "sess_7f6e5d4c",
      "dataset_id": "dataset_medical_records_2025",
      "status": "ACTIVE",
      "created_at": "2026-01-15T14:30:00Z",
      "expires_at": "2026-02-14T14:30:00Z"
    },
    {
      "session_id": "sess_8g7h6i5j",
      "dataset_id": "dataset_medical_records_2025",
      "status": "ACTIVE",
      "created_at": "2026-01-10T09:15:00Z",
      "expires_at": "2026-02-09T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Terminate Access

DELETE https://api.xase.ai/v1/access/{session_id}

# Request Body (optional)
{
  "reason": "Training completed early"
}

# Response (200 OK)
{
  "session_id": "sess_7f6e5d4c",
  "status": "TERMINATED",
  "terminated_at": "2026-01-20T11:42:17Z",
  "reason": "Training completed early"
}

Error responses

Policy Violation

{
  "error": {
    "type": "policy_violation",
    "message": "Access denied due to policy violation",
    "details": {
      "policy_id": "policy_medical_research",
      "policy_version": "1.2",
      "violations": [
        {
          "rule": "allowed_models",
          "message": "Model 'research-v3' is not in the allowed list: ['research-v1', 'research-v2']"
        }
      ]
    },
    "request_id": "req_d4e5f6g7"
  }
}

Approval Required

{
  "error": {
    "type": "approval_required",
    "message": "This access request requires explicit approval",
    "details": {
      "policy_id": "policy_medical_research",
      "policy_version": "1.2",
      "approval_request_id": "approval_e5f6g7h8",
      "approvers": ["data_admin@hospital.org"],
      "status": "PENDING"
    },
    "request_id": "req_d4e5f6g7"
  }
}

When approval is required, check the approval status using GET /v1/access/approvals/{approval_request_id}

Resource Not Found

{
  "error": {
    "type": "not_found",
    "message": "Session not found",
    "details": {
      "session_id": "sess_not_exists"
    },
    "request_id": "req_d4e5f6g7"
  }
}

Validation Error

{
  "error": {
    "type": "validation_error",
    "message": "Validation failed",
    "details": {
      "fields": [
        {
          "field": "duration",
          "message": "Invalid duration format. Use format like '30d', '24h', '2w'"
        },
        {
          "field": "purpose",
          "message": "Purpose is required"
        }
      ]
    },
    "request_id": "req_d4e5f6g7"
  }
}

SDK usage

Python SDK

import xase

client = xase.Client(api_key="sk_...")

# Request access
try:
    session = client.access(
        dataset="medical-records-2024",
        purpose="model-training",
        model_id="diagnostic-model-v2",
        duration="30d",
        metadata={
            "project": "Medical Diagnosis Improvement",
            "requester_notes": "Training on anonymized patient data"
        }
    )
    
    print(f"Access granted! Session ID: {session.id}")
    print(f"Expires at: {session.expires_at}")
    
except xase.PolicyViolationError as e:
    print(f"Access denied: {e.message}")
    for violation in e.violations:
        print(f"- {violation.rule}: {violation.message}")
        
except xase.ApprovalRequiredError as e:
    print(f"Approval required: {e.message}")
    print(f"Approval request ID: {e.approval_request_id}")
    print(f"Check status later with: client.get_approval_status('{e.approval_request_id}')")

Managing Access

# Get access session details
session = client.get_session("sess_7f6e5d4c")
print(f"Status: {session.status}")
print(f"Records accessed: {session.usage_stats.records_accessed}")

# List active sessions
active_sessions = client.list_sessions(status="ACTIVE")
for sess in active_sessions:
    print(f"Session {sess.id} for {sess.dataset_id}")
    
# Terminate session when done
client.terminate_session(
    session_id="sess_7f6e5d4c",
    reason="Training completed"
)

Next steps

Sessions APIUse active sessions to access data

Evidence APIGenerate and verify evidence bundles