The patient-controlled permission system that lets you access health data securely.

Access Grants

The grant system is the foundation of data access in AVYCENNA. Every piece of patient data you can see as a doctor is protected by an explicit, patient-controlled grant. There are no back-channels, no admin overrides.

How Grants Work

The patient is always in control. You can request access, but only the patient can grant it. The patient chooses exactly which data types you can see, and they can revoke access at any moment.

This is not just a compliance mechanism — it's a trust mechanism. Patients who understand and control their data sharing are more likely to share accurate, complete information.

Grant Lifecycle

Doctor Sends an Invite

You send a grant invitation from the dashboard (Patients → Invite Patient) or via the API:

curl -X POST https://api.avycenna.com/api/v1/grants/invite \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_email": "patient@example.com",
    "permissions": ["check_ins", "symptoms"],
    "message": "Hi — I am Dr. Chen. I would like to monitor your daily check-ins between visits.",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Patient Receives the Invite

The patient gets a push notification and in-app message. They can see your name, your message, and exactly which permissions you're requesting.

Patient Accepts (or Declines)

The patient reviews the invite and either accepts — with the option to modify which permissions they grant — or declines. If they accept with a subset of permissions (e.g., check-ins but not symptoms), you get exactly what they approved.

Doctor Gets Access

The grant activates immediately upon patient acceptance. The patient appears in your dashboard patient list within seconds.

Either Party Can Revoke

You can close the grant from the dashboard. The patient can revoke at any time from their app. Either action terminates access immediately.

Permissions

Grants are scoped to specific data types. You can request any combination:

Permission	What It Unlocks
`check_ins`	Daily check-in scores, journal notes, wearable biometrics
`symptoms`	Symptom logs with severity, dates, and notes
`medications`	Medication list and per-dose adherence logs

Patients can grant all three, or just one or two.

Grant Expiry

When creating an invite, you can set an expires_at date. After that date, the grant deactivates automatically — no action needed from either party. This is useful for:

Clinical trials with defined enrollment periods
Temporary monitoring after a procedure
Time-limited second opinions

If no expires_at is set, the grant is indefinite until explicitly revoked.

Revoking Access

Patient-initiated revocation: The patient taps Revoke in their app. Immediate effect.

Doctor-initiated closure: You can close a grant from the dashboard (patient detail → Close Grant) or via the API:

curl -X POST https://api.avycenna.com/api/v1/grants/revoke \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "grant_id": "grant_2xK9mNpQ",
    "reason": "Patient transferred to another provider"
  }'

Listing Your Grants

Doctor: View All Your Patients

curl https://api.avycenna.com/api/v1/grants/outgoing \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "grants": [
    {
      "id": "grant_2xK9mNpQ",
      "patient_id": "usr_7jRtHvBk",
      "patient_name": "Alex Morgan",
      "permissions": ["check_ins", "symptoms"],
      "status": "active",
      "granted_at": "2026-03-15T10:22:00Z",
      "expires_at": null
    }
  ]
}

Patient: View Incoming Invites

Patients use this endpoint in the mobile app to see pending invitations:

curl https://api.avycenna.com/api/v1/grants/incoming \
  -H "Authorization: Bearer eyJhbGci..."

Complete Invite Flow (curl)

# Step 1: Doctor sends invite
curl -X POST https://api.avycenna.com/api/v1/grants/invite \
  -H "Authorization: Bearer $DOCTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_email": "patient@example.com",
    "permissions": ["check_ins", "symptoms", "medications"],
    "message": "Hello, I would like to monitor your health data between our appointments."
  }'

# Response: { "grant_id": "grant_2xK9mNpQ", "status": "pending", "invited_at": "..." }

# Step 2: Patient accepts (from their mobile session)
curl -X POST https://api.avycenna.com/api/v1/grants/accept \
  -H "Authorization: Bearer $PATIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_id": "grant_2xK9mNpQ",
    "permissions": ["check_ins", "symptoms"]
  }'

# Response: { "grant_id": "grant_2xK9mNpQ", "status": "active", "permissions": ["check_ins", "symptoms"] }

# Step 3: Doctor fetches patient data
curl "https://api.avycenna.com/api/v1/grants/patient/usr_7jRtHvBk/check-ins?days=30" \
  -H "Authorization: Bearer $DOCTOR_TOKEN"

Access Grants

On this page