Settings → Licenses

Purpose

Manage the clinic's facility-level DEA + state licenses and mirror each clinic member's individual DEA practitioner / state veterinary licenses. The Settings → Licenses page is a navigation entry point for the same license CRUD flow exposed under Compliance → Licenses; it consolidates "everything license-related" under one tab so the clinic owner can manage facility licenses + see clinic-member coverage from one screen.

Regulatory basis: DEA registration of dispensers, modification of registration, and registrant identification in records; state veterinary medical boards (per-state).

When to use it

• Initial clinic setup: enter the facility's DEA registration + every state license + each prescriber's individual DEA practitioner license
• License renewal: when a license is renewed by the issuing authority
• DEA audit: an inspector will want to see the registration certificate first; this page renders the rollup
• Onboarding a new prescriber: their DEA practitioner license belongs on their personal account but flows into the clinic's Clinic Member Licenses tab here

Walkthrough

Step 1 — Open the licenses page

Navigate to /home/<slug>/settings/licenses. Two tabs: Facility Licenses + Clinic Member Licenses.

Step 2 — Add a facility license

On the Facility Licenses tab, click Add License in the top-right.

You're taken to the New License page (/compliance/licenses/new) in create mode with licenseScope locked to facility. Fill in:

• License Type (select): dea_registration, state_pharmacy_permit, state_facility_license, state_cs_registration, state_tech_registration
• State (select): Federal (DEA) for DEA registration; otherwise the 2-letter state code
• Issuing Authority (text): "Drug Enforcement Administration (DEA)" or the state board name
• License Number (text): the registration number
• Issue Date + Expiration Date (date)
• Notes (textarea, optional)

Click Add License. The page hard-refreshes after the action succeeds.

Step 3 — Add an individual (clinic member) license

To add an individual license, navigate to /home/settings/licenses (your personal settings, not the clinic's). Personal licenses must be added by the user who holds the license — owner/admin cannot add a license on someone else's behalf because RLS scopes individual licenses to the owner's personal account.

⚠️ Once added, the license shows up on the clinic's Clinic Member Licenses tab automatically (the loader unions licenses across all clinic members' personal accounts).

Step 4 — Renew a license

Click the row's actions menu → Renew. You're taken to the Renew License page (/compliance/licenses/<id>/renew) with current values shown (ADR-020 moved renew off the in-table dialog onto a full-page route). Provide new dates + (optional) new license number; submit. The existing row is UPDATED (not replaced); a new row in license_renewal_history captures the old → new delta.

Step 5 — Edit a license

Click the row's actions menu → Edit to fix typos in the issuing authority, license number, or dates. Edits do NOT create renewal-history rows.

Step 6 — Delete a license

Click the row's actions menu → Delete and confirm. The license is soft-deleted: it disappears from your list but the record is retained, so any transaction, renewal, or audit that referenced it keeps its history intact.

Field reference

See Compliance → Licenses § Field reference. Settings → Licenses uses the same license form and the same rules, so the field reference there applies here without exception.

Backing table: public.licenses. RLS:

• read: has_role_on_account(account_id) AND deleted_at IS NULL AND has_active_or_grace_subscription(account_id)
• insert: has_permission(auth.uid(), account_id, 'settings.manage') AND has_active_subscription(account_id)
• update: has_permission(auth.uid(), account_id, 'settings.manage') AND deleted_at IS NULL
• delete: blocked (use soft_delete_license SECURITY DEFINER RPC)

Soft-delete via soft_delete_license(target_id uuid) (shipped 2026-05-09 in migration 20260510023448); restore via restore_license(target_id uuid).

Edge cases

Individual license scope on a personal account

The form's licenseScope field is set by the entry point — the Facility tab's Add License forces facility; the Clinic Member Licenses tab on Settings is a read-only view (you can't add others' licenses). To add an individual license, navigate to your personal Settings → My Licenses page.

Unique constraint per (account, type, state, number)

Submitting a duplicate (account_id, license_type, state, license_number) tuple errors with a database 23505. Use Renew on the existing row instead.

Renewal history is preserved across edits

license_renewal_history rows are immutable; the table grows over time. The renewal-history view (Actions → Renewal History) shows every renewal cycle.

State 'federal' value vs. NULL

Facility-level DEA registration uses state='federal' (a sentinel). State-licensed practitioners use the 2-letter state code. The licenses table allows NULL for licenses with no geographic scope; in practice the form requires you to pick.

Common mistakes

• Recording a renewed license as a new license. Use Renew on the existing row. Adding a new row creates a phantom "old" license that confuses inspector reviews.
• Asking the owner to add an individual license. Owners cannot add licenses on someone else's personal account. The DVM must add their own.
• Forgetting a state-level CS registration. Where your state issues a controlled substance registration separate from the DEA registration, track it as license_type='state_cs_registration' so its renewal date gets the same alerting as everything else. CS Logbook does not know which states these are; check with your board.
• Recording the issuing authority inconsistently. Inspectors notice. Use the canonical board name; consider standardizing across all your clinics if you operate multiple.

Related

• Compliance → Licenses — full CRUD walkthrough + renewal-history details
• Compliance → Alerts — license expiration alerts auto-fire here
• Audits → DEA Audit Prep — license verification is the first checklist category
• Settings → Members — assign clinic position to enable the prescriber-of-record dispense flow