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, open Settings > My licenses inside your clinic (/home/<your-clinic>/profile/licenses; the same list is also at /home/settings/licenses). These are your personal licenses, 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.
• Assuming only the license holder can record it. This changed on 2026-09-15: a clinic manager with compliance permissions can now CREATE an individual license for a roster member, so a clinic is not blocked when an associate has not entered their own. The manager still cannot EDIT it afterwards, amendments belong to the holder. The older guidance that "the DVM must add their own" was correct before that change and is no longer.
• 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: alerts you create yourself; expiring licenses are listed on the Expiring tab
• Audits → DEA Audit Prep: license verification is the first checklist category
• Settings → Members: assign clinic position to enable the prescriber-of-record dispense flow